From de0f8ce16c03e09ba06c40da2aae807d731d15db Mon Sep 17 00:00:00 2001 From: lvluling Date: Wed, 16 Feb 2022 15:55:15 +0800 Subject: [PATCH] add description and examples of multiple arguments for Path.relative_to() --- Doc/library/pathlib.rst | 19 +++++++++++++++++-- 1 file changed, 17 insertions(+), 2 deletions(-) diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst index 7ab603fd133b86..5ebb21c5ca313c 100644 --- a/Doc/library/pathlib.rst +++ b/Doc/library/pathlib.rst @@ -540,8 +540,10 @@ Pure paths provide the following methods and properties: .. method:: PurePath.relative_to(*other) - Compute a version of this path relative to the path represented by - *other*. If it's impossible, ValueError is raised:: + Return the relative path to another path identified by *other*, each + element of *other* can be either a string representing a path segment, + or another path object implementing the :class:`PurePath`(or a subclass + of :class:`PurePath`). If the operation is impossible, ValueError is raised:: >>> p = PurePosixPath('/etc/passwd') >>> p.relative_to('/') @@ -555,6 +557,19 @@ Pure paths provide the following methods and properties: .format(str(self), str(formatted))) ValueError: '/etc/passwd' is not in the subpath of '/usr' OR one path is relative and the other absolute. + If *other* contains more than one element, rules for concatenation of + all elements is similarly to :class:`PurePath`:: + + >>> p = PurePosixPath('/tmp/foo/bar') + >>> p.relative_to('/tmp', 'foo') + PurePosixPath('bar') + >>> p.relative_to('/tmp', 'bar') + Traceback (most recent call last): + File "", line 1, in + File "pathlib.py", line 816, in relative_to + raise ValueError("{!r} is not in the subpath of {!r}" + ValueError: '/tmp/foo/bar' is not in the subpath of '/tmp/bar' OR one path is relative and the other is absolute. + NOTE: This function is part of :class:`PurePath` and works with strings. It does not check or access the underlying file structure.