backport ** on py3.10

Author: InertSloth

ROADMAP.md

@@ -21,7 +21,7 @@ Exploring bundling options for generating the single-file release:
 ## 🧪 Tests
 - verify every function has test coverage
 - check for redundant tests
-
+- improve test_is_excluded_raw_gitignore_double_star_diff to test our backport on py 3.10
 
 ## 🧑‍💻 Development
 

pyproject.toml

@@ -89,9 +89,11 @@ ignore = [
   "D104", # Missing docstring in public package
   "D105", # Missing docstring in magic method
   "D107", # Missing docstring in `__init__`
+  "D200", # One-line docstring should fit on one line
   "D203", # Force blank between class and docstring
   "D205", # 1 blank line required between summary line and description
   "D209", # Multi-line docstring closing quotes should be on a separate line
+  "D212", # Multi-line docstring summary should start at the first line
   "D213", # Force first line of docstring """ to not have text
   "D400", # First line should end with a period
   "D401", # First line of docstring should be in imperative mood

src/pocket_build/utils.py

@@ -7,7 +7,8 @@
 from collections.abc import Iterator
 from contextlib import contextmanager
 from dataclasses import dataclass
-from fnmatch import fnmatch
+from fnmatch import fnmatchcase, translate as _fnmatch_translate
+from functools import lru_cache
 from io import StringIO
 from pathlib import Path
 from typing import (
@@ -221,6 +222,41 @@ def is_excluded(path_entry: PathResolved, exclude_patterns: list[PathResolved])
     return is_excluded_raw(path, patterns, root)
 
 
+@lru_cache(maxsize=512)
+def _compile_glob_recursive(pattern: str) -> re.Pattern[str]:
+    r"""
+    Portable glob compiler:
+      - On Python ≥ 3.11 or when '**' is absent, use the stock translation.
+      - On Python ≤ 3.10 with '**', emulate recursive matching by joining
+        translated chunks with '.*' (which can cross path separators).
+    The returned regex uses the same '(?s:...)\Z' style as fnmatch.translate.
+    """
+    if sys.version_info >= (3, 11) or "**" not in pattern:
+        return re.compile(_fnmatch_translate(pattern))
+
+    # Split around '**' and translate each chunk using the stock translator.
+    parts = pattern.split("**")
+    chunk_regexes: list[str] = []
+    for part in parts:
+        rx = _fnmatch_translate(part)
+        # fnmatch.translate returns '(?s:...)\Z'; we need the inner '...'
+        if rx.startswith("(?s:") and rx.endswith(")\\Z"):
+            rx = rx[4:-2]
+        chunk_regexes.append(rx)
+
+    inner = ".*".join(chunk_regexes)  # allow crossing '/' between chunks
+    return re.compile(f"(?s:{inner})\\Z")
+
+
+def _fnmatch_portable(path: str, pattern: str) -> bool:
+    """
+    A drop-in replacement for fnmatch.fnmatch that backports '**' recursion on 3.10.
+    """
+    if sys.version_info >= (3, 11) or "**" not in pattern:
+        return fnmatchcase(path, pattern)
+    return bool(_compile_glob_recursive(pattern).match(path))
+
+
 def is_excluded_raw(  # noqa: PLR0911
     path: Path | str,
     exclude_patterns: list[str],
@@ -266,22 +302,17 @@ def is_excluded_raw(  # noqa: PLR0911
     for pattern in exclude_patterns:
         pat = pattern.replace("\\", "/")
 
-        if "**" in pat and sys.version_info < (3, 11):
-            logger.trace(
-                f"'**' behaves non-recursively on Python {sys.version_info[:2]}",
-            )
-
         # If pattern is absolute and under root, adjust to relative form
         if pat.startswith(str(root)):
             try:
                 pat_rel = str(Path(pat).relative_to(root)).replace("\\", "/")
             except ValueError:
                 pat_rel = pat  # not under root; treat as-is
-            if fnmatch(rel, pat_rel):
+            if _fnmatch_portable(rel, pat_rel):
                 return True
 
         # Otherwise treat pattern as relative glob
-        if fnmatch(rel, pat):
+        if _fnmatch_portable(rel, pat):
             return True
 
         # Optional directory-only semantics

tests/0_independant/test_is_excluded_raw.py

@@ -12,7 +12,6 @@
 - gitignore_double_star_diff — '**' not recursive unlike gitignore in ≤Py3.10.
 """
 
-import sys
 from pathlib import Path
 
 import pocket_build.utils as mod_utils
@@ -173,7 +172,7 @@ def test_is_excluded_raw_gitignore_double_star_diff(tmp_path: Path) -> None:
       Result:   True  (Python ≥3.11)
                 False (Python ≤3.10)
       Explanation:
-        - In Python ≤3.10, fnmatch treats '**' as simple '*', matching only one level.
+        - In Python ≤3.10, we backport 3.11 behaviour.
         - In Python ≥3.11, fnmatch matches recursively across directories.
         - Our code uses fnmatch directly, so it inherits the platform behavior.
           This test exists to document that difference, not to enforce one side.
@@ -189,12 +188,7 @@ def test_is_excluded_raw_gitignore_double_star_diff(tmp_path: Path) -> None:
     result = mod_utils.is_excluded_raw(nested, ["dir/**/*.py"], root)
 
     # --- verify ---
-    if sys.version_info >= (3, 11):
-        # Python 3.11+ uses recursive '**'
-        assert result, "Expected True on Python ≥3.11 where '**' is recursive"
-    else:
-        # Python 3.10 and earlier use single-level '*'
-        assert not result, "Expected False on Python ≤3.10 where '**' is shallow"
+    assert result, "Expected True on Python ≥3.11 where '**' is recursive"
 
 
 def test_is_excluded_wrapper_delegates(tmp_path: Path) -> None: