gh-57141: Make shallow argument to filecmp.dircmp keyword-only (#121767)

It is our general practice to make new optional parameters keyword-only,
even if the existing parameters are all positional-or-keyword. Passing
this parameter as positional would look confusing and could be error-prone
if additional parameters are added in the future.

diff --git a/Doc/library/filecmp.rst b/Doc/library/filecmp.rst
index 2a0670ffcc2cbce7df4dc2391ec9de3557f052c3..282d0e0d8db5cfd9694ba824821c5918e3080a0a 100644 (file)
--- a/Doc/library/filecmp.rst
+++ b/Doc/library/filecmp.rst
@@ -70,7 +70,7 @@ The :mod:`filecmp` module defines the following functions:
 The :class:`dircmp` class
 -------------------------
 
-.. class:: dircmp(a, b, ignore=None, hide=None, shallow=True)
+.. class:: dircmp(a, b, ignore=None, hide=None, *, shallow=True)
 
    Construct a new directory comparison object, to compare the directories *a*
    and *b*.  *ignore* is a list of names to ignore, and defaults to

diff --git a/Lib/filecmp.py b/Lib/filecmp.py
index 6ffc71fc059a80b2e5f1bc7cbacb47a9e2ce70bb..020ea694ca63e93d5d7daff628af780e4f5ae704 100644 (file)
--- a/Lib/filecmp.py
+++ b/Lib/filecmp.py
@@ -88,7 +88,7 @@ def _do_cmp(f1, f2):
 class dircmp:
     """A class that manages the comparison of 2 directories.
 
-    dircmp(a, b, ignore=None, hide=None, shallow=True)
+    dircmp(a, b, ignore=None, hide=None, *, shallow=True)
       A and B are directories.
       IGNORE is a list of names to ignore,
         defaults to DEFAULT_IGNORES.
@@ -124,7 +124,7 @@ class dircmp:
        in common_dirs.
      """
 
-    def __init__(self, a, b, ignore=None, hide=None, shallow=True): # Initialize
+    def __init__(self, a, b, ignore=None, hide=None, *, shallow=True): # Initialize
         self.left = a
         self.right = b
         if hide is None:
@@ -201,7 +201,7 @@ class dircmp:
             a_x = os.path.join(self.left, x)
             b_x = os.path.join(self.right, x)
             self.subdirs[x]  = self.__class__(a_x, b_x, self.ignore, self.hide,
-                                              self.shallow)
+                                              shallow=self.shallow)
 
     def phase4_closure(self): # Recursively call phase4() on subdirectories
         self.phase4()

diff --git a/Lib/test/test_filecmp.py b/Lib/test/test_filecmp.py
index b5df71678264a813c3339f21e1232b3cbd2f373d..1fb47163719ede40086b06867ac8bf0d924e117d 100644 (file)
--- a/Lib/test/test_filecmp.py
+++ b/Lib/test/test_filecmp.py
@@ -1,5 +1,6 @@
 import filecmp
 import os
+import re
 import shutil
 import tempfile
 import unittest
@@ -277,6 +278,17 @@ class DirCompareTestCase(unittest.TestCase):
         ]
         self._assert_report(d.report, expected_report)
 
+    def test_dircmp_shallow_is_keyword_only(self):
+        with self.assertRaisesRegex(
+            TypeError,
+            re.escape("dircmp.__init__() takes from 3 to 5 positional arguments but 6 were given"),
+        ):
+            filecmp.dircmp(self.dir, self.dir_same, None, None, True)
+        self.assertIsInstance(
+            filecmp.dircmp(self.dir, self.dir_same, None, None, shallow=True),
+            filecmp.dircmp,
+        )
+
     def test_dircmp_subdirs_type(self):
         """Check that dircmp.subdirs respects subclassing."""
         class MyDirCmp(filecmp.dircmp):

diff --git a/Misc/NEWS.d/next/Library/2024-07-14-06-24-02.gh-issue-57141.C3jhDh.rst b/Misc/NEWS.d/next/Library/2024-07-14-06-24-02.gh-issue-57141.C3jhDh.rst
new file mode 100644 (file)
index 0000000..33e9ab9
--- /dev/null
+++ b/Misc/NEWS.d/next/Library/2024-07-14-06-24-02.gh-issue-57141.C3jhDh.rst
@@ -0,0 +1,2 @@
+The *shallow* argument to :class:`filecmp.dircmp` (new in Python 3.13) is
+now keyword-only.