From 594bd8f246947574799d870fabd6f1d8020b14a5 Mon Sep 17 00:00:00 2001
From: Barney Gale <barney.gale@gmail.com>
Date: Thu, 30 Jun 2022 23:34:21 +0100
Subject: [PATCH] gh-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()`.
---
 Doc/library/pathlib.rst                       |  4 ++--
 Lib/pathlib.py                                | 21 +++++++++++++------
 Lib/test/test_pathlib.py                      |  6 ++++--
 ...2-07-01-00-01-22.gh-issue-78707.fHGSuM.rst |  3 +++
 4 files changed, 24 insertions(+), 10 deletions(-)
 create mode 100644 Misc/NEWS.d/next/Library/2022-07-01-00-01-22.gh-issue-78707.fHGSuM.rst

diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst
index 2b798698385fd1..aef4eaec9d2f61 100644
--- a/Doc/library/pathlib.rst
+++ b/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::
diff --git a/Lib/pathlib.py b/Lib/pathlib.py
index bb440c9d57216a..5f34ae51cf2100 100644
--- a/Lib/pathlib.py
+++ b/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,8 +649,11 @@ 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
@@ -658,7 +661,7 @@ def relative_to(self, *other):
             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
diff --git a/Lib/test/test_pathlib.py b/Lib/test/test_pathlib.py
index a42619853399f2..fee75677f0e465 100644
--- a/Lib/test/test_pathlib.py
+++ b/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')))
diff --git a/Misc/NEWS.d/next/Library/2022-07-01-00-01-22.gh-issue-78707.fHGSuM.rst b/Misc/NEWS.d/next/Library/2022-07-01-00-01-22.gh-issue-78707.fHGSuM.rst
new file mode 100644
index 00000000000000..25013f476559df
--- /dev/null
+++ b/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`.