gh-117074: Update Traversable.joinpath docs to the 3.11+ protocol (GH-117113)

encukou · web-flow · commit e569f9132b5b · 2024-04-02T16:08:16.000+02:00
diff --git a/Doc/library/importlib.resources.abc.rst b/Doc/library/importlib.resources.abc.rst
@@ -109,13 +109,35 @@
 
        Return True if self is a file.
 
-    .. abstractmethod:: joinpath(child)
+    .. abstractmethod:: joinpath(*pathsegments)
 
-       Return Traversable child in self.
+       Traverse directories according to *pathsegments* and return
+       the result as :class:`!Traversable`.
+
+       Each *pathsegments* argument may contain multiple names separated by
+       forward slashes (``/``, ``posixpath.sep`` ).
+       For example, the following are equivalent::
+
+           files.joinpath('subdir', 'subsuddir', 'file.txt')
+           files.joinpath('subdir/subsuddir/file.txt')
+
+       Note that some :class:`!Traversable` implementations
+       might not be updated to the latest version of the protocol.
+       For compatibility with such implementations, provide a single argument
+       without path separators to each call to ``joinpath``. For example::
+
+           files.joinpath('subdir').joinpath('subsubdir').joinpath('file.txt')
+
+       .. versionchanged:: 3.11
+
+          ``joinpath`` accepts multiple *pathsegments*, and these segments
+          may contain forward slashes as path separators.
+          Previously, only a single *child* argument was accepted.
 
     .. abstractmethod:: __truediv__(child)
 
        Return Traversable child in self.
+       Equivalent to ``joinpath(child)``.
 
     .. abstractmethod:: open(mode='r', *args, **kwargs)
 
