GH-99334: Explain that `PurePath.is_relative_to()` is purely lexical. (#114031)

diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst
index b924f470e0be0448f006c55fe416ed89262e2bed..faff3bc5823cb4e5d5b6cf4946b25ba8b36a7c8b 100644 (file)
--- a/Doc/library/pathlib.rst
+++ b/Doc/library/pathlib.rst
@@ -515,6 +515,13 @@ Pure paths provide the following methods and properties:
       >>> p.is_relative_to('/usr')
       False
 
+   This method is string-based; it neither accesses the filesystem nor treats
+   "``..``" segments specially. The following code is equivalent:
+
+      >>> u = PurePath('/usr')
+      >>> u == p or u in p.parents
+      False
+
    .. versionadded:: 3.9
 
    .. deprecated-removed:: 3.12 3.14