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

This brings `relative_to()` and `is_relative_to()` more in line with other
pathlib methods like `rename()` and `symlink_to()`.

Author: barneygale

Doc/library/pathlib.rst

@@ -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.
 
@@ -564,7 +564,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::

Lib/pathlib.py

@@ -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, *args):
         """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.
@@ -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 args:
+            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,) + args)
         if to_root:
             to_abs_parts = [to_drv, to_root] + to_parts[1:]
         else:
@@ -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, *args):
         """Return True if the path is relative to another path or False.
         """
+        if args:
+            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,) + args)
         try:
-            self.relative_to(*other)
+            self.relative_to(other)
             return True
         except ValueError:
             return False

Lib/test/test_pathlib.py

@@ -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'))
@@ -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')))

Misc/NEWS.d/next/Library/2022-07-01-00-01-22.gh-issue-78707.fHGSuM.rst

@@ -0,0 +1,3 @@
+Deprecate passing more than one argument to
+:meth:`pathlib.PurePath.relative_to` and
+:meth:`~pathlib.PurePath.is_relative_to`.