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.

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

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 @@ def phase4(self): # Find out differences between common subdirectories
             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()

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 @@ def test_dircmp_shallow_same_file(self):
         ]
         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):

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.