From: Petr Viktorin Date: Tue, 2 Apr 2024 14:08:16 +0000 (+0200) Subject: gh-117074: Update Traversable.joinpath docs to the 3.11+ protocol (GH-117113) X-Git-Tag: v3.13.0a6~74 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=e569f9132b5bdc1c103116a020e19e3ccc20cf34;p=thirdparty%2FPython%2Fcpython.git gh-117074: Update Traversable.joinpath docs to the 3.11+ protocol (GH-117113) --- diff --git a/Doc/library/importlib.resources.abc.rst b/Doc/library/importlib.resources.abc.rst index c508b6ba965c..c25c48530722 100644 --- 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)