Skip to content

gh-78707: deprecate passing >1 argument to PurePath.[is_]relative_to() #94469

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Merged
Show file tree
Hide file tree
Changes from 2 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 14 additions & 3 deletions Doc/library/pathlib.rst
Original file line number Diff line number Diff line change
Expand Up @@ -490,7 +490,7 @@ Pure paths provide the following methods and properties:
True


.. method:: PurePath.is_relative_to(*other)
.. method:: PurePath.is_relative_to(other)

Return whether or not this path is relative to the *other* path.

Expand All @@ -502,6 +502,10 @@ Pure paths provide the following methods and properties:

.. versionadded:: 3.9

.. deprecated:: 3.12

Support for supplying additional arguments is deprecated; if supplied,
they are joined with *other*.

.. method:: PurePath.is_reserved()

Expand Down Expand Up @@ -564,7 +568,7 @@ Pure paths provide the following methods and properties:
True


.. method:: PurePath.relative_to(*other)
.. 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::
Expand All @@ -581,8 +585,15 @@ 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.

NOTE: This function is part of :class:`PurePath` and works with strings. It does not check or access the underlying file structure.
.. note:

This function is part of :class:`PurePath` and works with strings. It
does not access the filesystem.

.. deprecated:: 3.12

Passing additional arguments is deprecated; if supplied, they are joined
with *other*.

.. method:: PurePath.with_name(name)

Expand Down
21 changes: 15 additions & 6 deletions Lib/pathlib.py
Original file line number Diff line number Diff line change
Expand Up @@ -640,7 +640,7 @@ def with_suffix(self, suffix):
return self._from_parsed_parts(self._drv, self._root,
self._parts[:-1] + [name])

def relative_to(self, *other):
def relative_to(self, other, /, *_deprecated):
"""Return the relative path to another path identified by the passed
arguments. If the operation is not possible (because this is not
a subpath of the other path), raise ValueError.
Expand All @@ -649,16 +649,19 @@ def relative_to(self, *other):
# separate parts, i.e.:
# Path('c:/').relative_to('c:') gives Path('/')
# Path('c:/').relative_to('/') raise ValueError
if not other:
raise TypeError("need at least one argument")
if _deprecated:
warnings.warn("support for supplying more than one argument to "
"pathlib.PurePath.relative_to() is deprecated and "
"scheduled for removal in Python 3.14.",
DeprecationWarning, stacklevel=2)
parts = self._parts
drv = self._drv
root = self._root
if root:
abs_parts = [drv, root] + parts[1:]
else:
abs_parts = parts
to_drv, to_root, to_parts = self._parse_args(other)
to_drv, to_root, to_parts = self._parse_args((other,) + _deprecated)
if to_root:
to_abs_parts = [to_drv, to_root] + to_parts[1:]
else:
Expand All @@ -673,11 +676,17 @@ def relative_to(self, *other):
return self._from_parsed_parts('', root if n == 1 else '',
abs_parts[n:])

def is_relative_to(self, *other):
def is_relative_to(self, other, /, *_deprecated):
"""Return True if the path is relative to another path or False.
"""
if _deprecated:
warnings.warn("support for supplying more than one argument to "
"pathlib.PurePath.is_relative_to() is deprecated "
"and scheduled for removal in Python 3.14.",
DeprecationWarning, stacklevel=2)
other = self._from_parts((other,) + _deprecated)
try:
self.relative_to(*other)
self.relative_to(other)
return True
except ValueError:
return False
Expand Down
6 changes: 4 additions & 2 deletions Lib/test/test_pathlib.py
Original file line number Diff line number Diff line change
Expand Up @@ -637,7 +637,8 @@ def test_relative_to_common(self):
self.assertEqual(p.relative_to(P('a/b')), P())
self.assertEqual(p.relative_to('a/b'), P())
# With several args.
self.assertEqual(p.relative_to('a', 'b'), P())
with self.assertWarns(DeprecationWarning):
p.relative_to('a', 'b')
# Unrelated paths.
self.assertRaises(ValueError, p.relative_to, P('c'))
self.assertRaises(ValueError, p.relative_to, P('a/b/c'))
Expand Down Expand Up @@ -671,7 +672,8 @@ def test_is_relative_to_common(self):
self.assertTrue(p.is_relative_to(P('a/b')))
self.assertTrue(p.is_relative_to('a/b'))
# With several args.
self.assertTrue(p.is_relative_to('a', 'b'))
with self.assertWarns(DeprecationWarning):
p.is_relative_to('a', 'b')
# Unrelated paths.
self.assertFalse(p.is_relative_to(P('c')))
self.assertFalse(p.is_relative_to(P('a/b/c')))
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
Deprecate passing more than one argument to
:meth:`pathlib.PurePath.relative_to` and
:meth:`~pathlib.PurePath.is_relative_to`.