gh-74598: add fnmatch.filterfalse for excluding names

Doc/library/fnmatch.rst

@@ -79,11 +79,21 @@ cache the compiled regex patterns in the following functions: :func:`fnmatch`,
 .. function:: filter(names, pat)
 
    Construct a list from those elements of the :term:`iterable` *names*
-   that match pattern *pat*.
+   that match the pattern *pat*.
    It is the same as ``[n for n in names if fnmatch(n, pat)]``,
    but implemented more efficiently.
 
 
+.. function:: filterfalse(names, pat)
+
+   Construct a list from those elements of the :term:`iterable` *names*
+   that do not match the pattern *pat*.
+   It is the same as ``[n for n in names if not fnmatch(n, pat)]``,
+   but implemented more efficiently.
+
+   .. versionadded:: 3.14
+
+
 .. function:: translate(pat)
 
    Return the shell-style pattern *pat* converted to a regular expression for

Doc/whatsnew/3.14.rst

@@ -92,6 +92,13 @@ ast
 Added :func:`ast.compare` for comparing two ASTs.
 (Contributed by Batuhan Taskaya and Jeremy Hylton in :issue:`15987`.)
 
+fnmatch
+-------
+
+* Added :func:`fnmatch.filterfalse` for excluding names matching a pattern.
+
+  (Contributed by Bénédikt Tran in :gh:`74598`.)
+
 os
 --
 

Lib/fnmatch.py

@@ -61,6 +61,22 @@ def filter(names, pat):
                 result.append(name)
     return result
 
+def filterfalse(names, pat):
+    """Construct a list from those elements of the iterable NAMES that do not match PAT."""
+    result = []
+    pat = os.path.normcase(pat)
+    match = _compile_pattern(pat)
+    if os.path is posixpath:
+        # normcase on posix is NOP. Optimize it away from the loop.
+        for name in names:
+            if match(name) is None:
+                result.append(name)
+    else:
+        for name in names:
+            if match(os.path.normcase(name)) is None:
+                result.append(name)
+    return result
+
 def fnmatchcase(name, pat):
     """Test whether FILENAME matches PATTERN, including case.
 

Lib/test/test_fnmatch.py

@@ -5,7 +5,7 @@
 import string
 import warnings
 
-from fnmatch import fnmatch, fnmatchcase, translate, filter
+from fnmatch import fnmatch, fnmatchcase, translate, filter, filterfalse
 
 class FnmatchTestCase(unittest.TestCase):
 
@@ -258,6 +258,12 @@ def test_filter(self):
         self.assertEqual(filter([b'Python', b'Ruby', b'Perl', b'Tcl'], b'P*'),
                          [b'Python', b'Perl'])
 
+    def test_filterfalse(self):
+        actual = filterfalse(['Python', 'Ruby', 'Perl', 'Tcl'], 'P*')
+        self.assertListEqual(actual, ['Ruby', 'Tcl'])
+        actual = filterfalse([b'Python', b'Ruby', b'Perl', b'Tcl'], b'P*')
+        self.assertListEqual(actual, [b'Ruby', b'Tcl'])
+
     def test_mix_bytes_str(self):
         self.assertRaises(TypeError, filter, ['test'], b'*')
         self.assertRaises(TypeError, filter, [b'test'], '*')

Misc/NEWS.d/next/Library/2024-06-30-17-00-00.gh-issue-74598.1gVy_8.rst

@@ -0,0 +1,2 @@
+Add :func:`fnmatch.filterfalse` for excluding names matching a pattern.
+Patch by Bénédikt Tran.