fastglob 0.1.0__tar.gz

fastglob-0.1.0/.gitignore

@@ -0,0 +1,54 @@
+# Fast Glob — gitignore (minimal, covers agentic + build artifacts)
+# Secrets: .mcp.json and code_aid_query.sh contain live credentials and MUST NOT be committed to public GitHub.
+# For public release, scrub them from history before publishing (see AGENTS.md RELEASE HYGIENE).
+.mcp.json
+code_aid_query.sh
+
+# Large generated index (87MB) — tracked previously, now ignored
+.ix/
+.ix/shard.ix
+.ix/shard.ix.delta
+.ix/beacon.json
+
+# Python cache + packaging artifacts
+__pycache__/
+*.pyc
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+*.egg-info/
+.venv/
+dist/
+build/
+.coverage
+.coverage.*
+htmlcov/
+
+# Agentic artifacts (must not be committed to public GitHub)
+.sniper/
+out/
+probes/
+fastglob.jsonl
+final-fblob.jsonl
+pi-session-fastglob.html
+
+# Compat run artifact (regenerated by every `make compat`; embeds
+# machine-specific absolute paths and per-run timings — not a reference)
+tests/compat/candidate.json
+
+# Benchmark generated trees and results
+bench/trees/
+bench/results/*.json
+bench/results/*.md
+!bench/results/baseline.md
+
+# Rust build artifacts
+src/target/
+
+# Misc
+.DS_Store
+*.swp
+*~
+
+# Maat audit reports (local-only)
+.maat/

fastglob-0.1.0/PKG-INFO

@@ -0,0 +1,21 @@
+Metadata-Version: 2.5
+Name: fastglob
+Version: 0.1.0
+Summary: Python compatibility wrapper around the fastglob engine
+Project-URL: Repository, https://github.com/moeshawky/fastglob
+Author-email: Moe Shawky <moe@libermoe.com>
+Maintainer-email: Moe Shawky <moe@libermoe.com>
+License-Expression: MIT
+Keywords: filesystem,glob,linux,pathname,pattern-matching
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Utilities
+Requires-Python: >=3.8
+Provides-Extra: dev
+Requires-Dist: mypy>=1.4; extra == 'dev'
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.15; extra == 'dev'

fastglob-0.1.0/fastglob/__init__.py

@@ -0,0 +1,347 @@
+"""fastglob — Python-compatibility wrapper around the fastglob engine.
+
+This is a SEPARATE package: it never shadows the stdlib ``glob`` module
+(``import glob`` still gives you the standard library). Usage:
+
+    import fastglob
+    fastglob.glob("*.py", recursive=True, include_hidden=False)
+    fastglob.iglob("a/**/b.txt", recursive=True)
+    fastglob.escape("a*b")  -> "a[*]b"
+    fastglob.escape(b"a*b") -> b"a[*]b"   # bytes pattern -> bytes result
+
+Documented mechanics (keep these in mind when using in hot loops):
+
+* Every call SHELLS OUT to the ``fastglob`` binary (one process per call).
+  The engine does all traversal/matching natively; this package only
+  marshals arguments and decodes NUL-delimited, byte-exact output.
+* The binary is located via ``$FASTGLOB_BIN`` if set, otherwise
+  ``<repo>/src/target/release/fastglob`` (build it with ``make build``).
+* ``dir_fd`` is passed to the child by dup()ing the fd with CLOEXEC
+  cleared and passing ``--dir-fd N`` plus ``pass_fds`` (PEP 446: fds from
+  ``os.open`` are close-on-exec and ``subprocess`` closes fds >= 3 in the
+  child unless listed in ``pass_fds``).
+* Result TYPE follows the PATTERN type (stdlib parity — VERIFIED against
+  CPython 3.12: ``glob.escape(b'a*b') == b'a[*]b'``, ``glob(b'*.py')``
+  yields bytes elements; the reference branches on
+  ``isinstance(pathname, bytes)``): str/PathLike patterns give str results
+  decoded via ``os.fsdecode`` (surrogateescape), so arbitrary byte
+  filenames round-trip exactly; bytes patterns give raw bytes results —
+  the engine output is already byte-exact, so bytes mode simply skips
+  decoding (no lossy round-trip).
+"""
+
+from __future__ import annotations
+
+import fcntl
+import os
+import subprocess
+from pathlib import Path
+from typing import Iterator, cast, overload
+
+__all__ = ["escape", "glob", "iglob"]
+
+__version__ = "0.1.0"
+
+# Filesystem path arguments: str, bytes, or a PathLike whose ``__fspath__``
+# returns str or bytes (stdlib parity — CPython glob accepts all three).
+# Bare ``os.PathLike`` would be ``os.PathLike[Any]`` (implicit Any), which
+# mypy --strict (disallow_any_generics) rejects.
+_PathArg = str | bytes | os.PathLike[str] | os.PathLike[bytes]
+
+
+def _bin() -> str:
+    b = os.environ.get("FASTGLOB_BIN")
+    if b:
+        return b
+    repo = Path(__file__).resolve().parent.parent.parent
+    return str(repo / "src" / "target" / "release" / "fastglob")
+
+
+def _fs(x: _PathArg) -> bytes:
+    return os.fsencode(x)
+
+
+def _wants_bytes(x: _PathArg) -> bool:
+    """True when results for path argument ``x`` must be bytes-typed.
+
+    Mirrors the reference implementation's type preservation (CPython
+    Lib/glob.py branches on ``isinstance(pathname, bytes)``; VERIFIED live
+    on CPython 3.12: ``glob.escape(b'a*b') == b'a[*]b'``, ``glob(b'*.py')``
+    yields bytes elements): plain bytes/bytearray follow bytes; a PathLike
+    follows whatever its ``__fspath__`` returns, exactly like ``os.fspath``
+    typing. str (and str-fspath PathLike) -> False.
+    """
+    if isinstance(x, (bytes, bytearray)):
+        return True
+    if hasattr(x, "__fspath__"):
+        return isinstance(os.fspath(x), bytes)
+    return False
+
+
+def _run(args: list[bytes], pass_fds: tuple[int, ...] = ()) -> bytes:
+    p = subprocess.run(
+        [_bin().encode(), *args],
+        capture_output=True,
+        pass_fds=pass_fds,
+    )
+    if p.returncode != 0:
+        msg = p.stderr.decode("utf-8", "replace").strip()
+        raise RuntimeError(f"fastglob exited {p.returncode}: {msg}")
+    return p.stdout
+
+
+def _paths(out: bytes, *, as_bytes: bool = False) -> list[str] | list[bytes]:
+    """NUL-split byte-exact engine output into a result list.
+
+    Inputs:
+        out: raw engine stdout (records separated by NUL)
+        as_bytes: False (default) -> decode each record via ``os.fsdecode``
+            (surrogateescape), returning List[str]; True -> return the raw
+            records as List[bytes]. Used when the caller's pattern was
+            bytes so results preserve the input type (Ct38): no decoding,
+            no lossy round-trip.
+    Output:
+        List[str] or List[bytes] — one element per engine record
+    Errors:
+        None (pure split/decode)
+    """
+    parts = out.split(b"\0")
+    if parts and parts[-1] == b"":
+        parts = parts[:-1]
+    if as_bytes:
+        return list(parts)
+    return [os.fsdecode(x) for x in parts]
+
+
+def _call(
+    pathname: _PathArg,
+    root_dir: _PathArg | None,
+    dir_fd: int | None,
+    recursive: bool,
+    include_hidden: bool,
+    as_bytes: bool = False,
+) -> list[str] | list[bytes]:
+    """Execute the fastglob engine with the given pattern and options.
+
+    Inputs:
+        pathname: glob pattern as str/bytes/PathLike. The RESULT type follows
+            the PATTERN type (Ct38): bytes pattern -> List[bytes] (raw engine
+            records); str or PathLike -> List[str] via fsdecode.
+        root_dir: optional filesystem origin shift (None = cwd). Its type is
+            independent of the result type — e.g. root_dir=str with a bytes
+            pattern is supported and yields bytes results.
+        dir_fd: optional open directory fd to resolve relative patterns against
+        recursive: when True, ``**`` matches zero or more directories
+        include_hidden: when True, ``*``/``?``/``**`` match dot-prefixed names
+    Output:
+        Matching pathnames as List[str] or List[bytes], duplicates preserved,
+        order unspecified
+    Errors:
+        RuntimeError if the engine exits non-zero (misuse -> exit 2)
+        TypeError/ValueError if pathname/root_dir is not str/bytes/PathLike,
+            or dir_fd is not a valid open int fd
+    """
+    want_bytes = _wants_bytes(pathname)
+    args: list[bytes] = []
+    if recursive:
+        args.append(b"--recursive")
+    if include_hidden:
+        args.append(b"--include-hidden")
+    if root_dir is not None:
+        args += [b"--root-dir", _fs(root_dir)]
+    args += [b"--null", b"--", _fs(pathname)]
+
+    if dir_fd is not None:
+        # Validate dir_fd type and value before use (Level A contract).
+        if not isinstance(dir_fd, int):
+            raise TypeError(f"dir_fd must be int, got {type(dir_fd).__name__}")
+        if dir_fd < 0:
+            raise ValueError(f"dir_fd must be non-negative, got {dir_fd}")
+        # Validate that dir_fd is an open directory fd (fstat).
+        try:
+            os.fstat(dir_fd)
+        except OSError as e:
+            raise ValueError(f"dir_fd {dir_fd} is not a valid open fd: {e}") from e
+        # Atomic inheritable dup: prefer F_DUPFD (CLOEXEC cleared) which is
+        # atomic; fallback to dup()+set_inheritable which is two syscalls but
+        # uses the Python-level atomic helper (PEP 446). The old dup()+fcntl
+        # F_SETFD clearing was non-atomic (race window between dup and fcntl).
+        try:
+            # Use F_DUPFD to atomically dup with CLOEXEC cleared (new fd >=3).
+            d = fcntl.fcntl(dir_fd, fcntl.F_DUPFD, 3)
+            # Ensure inheritable (CLOEXEC cleared) — F_DUPFD already clears,
+            # but explicitly set for portability.
+            os.set_inheritable(d, True)
+        except (OSError, AttributeError):
+            d = os.dup(dir_fd)
+            try:
+                os.set_inheritable(d, True)
+            except OSError:
+                os.close(d)
+                raise
+        try:
+            args += [b"--dir-fd", str(d).encode()]
+            out = _run(args, pass_fds=(d,))
+        finally:
+            os.close(d)
+    else:
+        out = _run(args)
+    return _paths(out, as_bytes=want_bytes)
+
+
+@overload
+def glob(
+    pathname: str | os.PathLike[str],
+    *,
+    root_dir: _PathArg | None = None,
+    dir_fd: int | None = None,
+    recursive: bool = False,
+    include_hidden: bool = False,
+) -> list[str]: ...
+
+
+@overload
+def glob(
+    pathname: bytes | os.PathLike[bytes],
+    *,
+    root_dir: _PathArg | None = None,
+    dir_fd: int | None = None,
+    recursive: bool = False,
+    include_hidden: bool = False,
+) -> list[bytes]: ...
+
+
+def glob(
+    pathname: _PathArg,
+    *,
+    root_dir: _PathArg | None = None,
+    dir_fd: int | None = None,
+    recursive: bool = False,
+    include_hidden: bool = False,
+) -> list[str] | list[bytes]:
+    """Return a list of paths matching ``pathname`` (stdlib-glob kwargs).
+
+    Type contract (stdlib parity — VERIFIED against CPython 3.12:
+    ``glob.glob(b'*.py')`` yields bytes elements):
+        str or PathLike pattern  -> List[str]   (fsdecode/surrogateescape)
+        bytes pattern            -> List[bytes] (raw engine bytes)
+
+    Example (result type follows the PATTERN type; root_dir type is
+    independent — only the pattern decides str-vs-bytes)::
+
+        fastglob.glob("*.py", root_dir="src")     # ['x.py', ...]   (str)
+        fastglob.glob(b"*.py", root_dir=b"src")   # [b'x.py', ...]   (bytes)
+        fastglob.glob(b"*", root_dir="/tmp")      # [b'file', ...]   (bytes)
+
+    Not supported (raises TypeError, like the stdlib): patterns that are
+    neither str, bytes, nor PathLike.
+
+    Inputs:
+        pathname: pattern (str/bytes/PathLike)
+        root_dir: optional root directory shift (str/bytes/PathLike or None)
+        dir_fd: optional directory fd (int) for relative resolution
+        recursive: enable ``**`` zero-or-more-dirs matching
+        include_hidden: allow ``*``/``?``/``**`` to match dotfiles
+    Output:
+        List[str] or List[bytes] — matching pathnames (duplicates preserved,
+        order unspecified)
+    Errors:
+        Propagates RuntimeError/TypeError/ValueError from ``_call``
+    """
+    return _call(
+        pathname,
+        root_dir,
+        dir_fd,
+        recursive,
+        include_hidden,
+        as_bytes=_wants_bytes(pathname),
+    )
+
+
+@overload
+def iglob(
+    pathname: str | os.PathLike[str],
+    *,
+    root_dir: _PathArg | None = None,
+    dir_fd: int | None = None,
+    recursive: bool = False,
+    include_hidden: bool = False,
+) -> Iterator[str]: ...
+
+
+@overload
+def iglob(
+    pathname: bytes | os.PathLike[bytes],
+    *,
+    root_dir: _PathArg | None = None,
+    dir_fd: int | None = None,
+    recursive: bool = False,
+    include_hidden: bool = False,
+) -> Iterator[bytes]: ...
+
+
+def iglob(
+    pathname: _PathArg,
+    *,
+    root_dir: _PathArg | None = None,
+    dir_fd: int | None = None,
+    recursive: bool = False,
+    include_hidden: bool = False,
+) -> Iterator[str] | Iterator[bytes]:
+    """Yield paths matching ``pathname`` (one binary call per iglob).
+
+    Same type contract as ``glob``: str/PathLike pattern yields str items,
+    bytes pattern yields bytes items (stdlib parity, VERIFIED on CPython
+    3.12). Example::
+
+        next(fastglob.iglob(b"*"))  # -> bytes
+        next(fastglob.iglob("*"))   # -> str
+
+    Inputs: same as ``glob``.
+    Output: Iterator[str] or Iterator[bytes] — lazily yields each match
+    (materialized via one engine call)
+    Errors: same as ``glob``
+    """
+    items = _call(
+        pathname,
+        root_dir,
+        dir_fd,
+        recursive,
+        include_hidden,
+        as_bytes=_wants_bytes(pathname),
+    )
+    # _call's union return erases the per-element type; the runtime contract
+    # (Ct38, test-verified) is that items is all-str or all-bytes.
+    return cast("Iterator[str] | Iterator[bytes]", (p for p in items))
+
+
+@overload
+def escape(pathname: str | os.PathLike[str]) -> str: ...
+
+
+@overload
+def escape(pathname: bytes | os.PathLike[bytes]) -> bytes: ...
+
+
+def escape(pathname: _PathArg) -> str | bytes:
+    """Escape all glob special characters (port of ``glob.escape``).
+
+    Type contract (stdlib parity — VERIFIED against CPython 3.12:
+    ``glob.escape(b'a*b') == b'a[*]b'``):
+
+        >>> escape('a*b')
+        'a[*]b'
+        >>> escape(b'a*b')
+        b'a[*]b'
+
+    PathLike input follows its ``__fspath__`` typing (str-fspath -> str
+    result, bytes-fspath -> bytes result); anything else raises TypeError.
+    Escaping always operates on the engine's byte-exact output: bytes
+    results are returned raw (no lossy round-trip); str results are decoded
+    via fsdecode (surrogateescape).
+    """
+    out = _run([b"escape", b"--null", b"--", _fs(pathname)])
+    first = out.split(b"\0")[0]
+    if _wants_bytes(pathname):
+        return first
+    return os.fsdecode(first)

fastglob-0.1.0/pyproject.toml

@@ -0,0 +1,140 @@
+# Packaging metadata for the `fastglob` Python package (repo layout: python/fastglob/).
+# Exists so that the documented command `pip install -e python` (README.md, docs/api.md)
+# actually succeeds — PEP 517/660 editable installs require build metadata.
+#
+# MAINTENANCE CONTRACT:
+# - `version` MUST stay exactly equal to __version__ in python/fastglob/__init__.py
+#   (single source of truth is __init__.py; update both together or wire dynamic
+#   metadata later — do NOT let them drift).
+# - Build backend: hatchling (2026 stack, measured 2026-08-23 via `uv build`
+#   probe: wheel contains exactly fastglob/__init__.py + fastglob/py.typed +
+#   dist-info; PEP 660 editable verified). Do NOT add a second top-level
+#   directory under python/ without re-verifying the wheel file list.
+# - Deliberately minimal per assignment W4: no entry-points. Identity fields
+#   the operator has not specified (authors/maintainers, copyright holder)
+#   mirror the Rust pass placeholders (src/Cargo.toml, LICENSE TODO) —
+#   replace together before publishing.
+# - python/ IS the src root of this subproject: the package dir python/fastglob/
+#   is imported via `pip install -e python` or the documented PYTHONPATH=python
+#   fallback. Do not add a repo-root pyproject.toml claiming the `fastglob`
+#   package — it would shadow this file.
+
+[build-system]
+requires = ["hatchling>=1.26"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build]
+# Dev tooling artifacts — never ship in the distribution (measured 2026-08-23:
+# uv.lock/.python-version and the tools' own cache dirs leaked into the first
+# sdist; excluded here). Note: hatchling's VCS-aware sdist also carries the
+# repo-root .gitignore into the sdist root — harmless at install time and
+# not removable via `exclude` (measured), so it is accepted, not fought.
+exclude = [
+    ".python-version",
+    "uv.lock",
+    ".coverage",
+    ".ruff_cache",
+    ".mypy_cache",
+]
+
+[project]
+name = "fastglob"
+version = "0.1.0"
+description = "Python compatibility wrapper around the fastglob engine"
+# TODO (operator): add a per-package README (hatchling requires the readme
+# inside python/, so the repo-root README.md cannot be referenced directly).
+# Until then the wheel carries the one-line description; the repo README
+# documents this package fully.
+license = "MIT"
+requires-python = ">=3.8"
+authors = [{ name = "Moe Shawky", email = "moe@libermoe.com" }]
+maintainers = [{ name = "Moe Shawky", email = "moe@libermoe.com" }]
+keywords = ["glob", "pathname", "pattern-matching", "filesystem", "linux"]
+classifiers = [
+    # Tested legs only: 3.8 = requires-python floor (enforced via ruff
+    # target-version py38, measured), 3.12 = the oracle interpreter.
+    # Extend when CI gains matrix legs — do not claim untested versions.
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.12",
+    "Operating System :: POSIX :: Linux",
+    "Intended Audience :: Developers",
+    "Topic :: Utilities",
+]
+dependencies = [] # stdlib only — the engine is a subprocess, not a dependency
+
+[project.optional-dependencies]
+# `pip install -e "python[dev]"` — the quality-gate stack (G1-G6).
+# No types-* stubs: zero third-party runtime dependencies (stdlib stubs
+# ship with mypy). Dev-tool floors are measured, not assumed: mypy 2.x
+# requires interpreter >=3.10 (mypy 1.x covers 3.8-3.9), so the floors are
+# written as ranges that resolve across the full requires-python span.
+dev = [
+    "ruff>=0.15",
+    "mypy>=1.4",
+    "pytest>=8",
+    "pytest-cov>=5",
+]
+
+[project.urls]
+Repository = "https://github.com/moeshawky/fastglob"
+
+# ── Ruff (linter + formatter) ─────────────────────────────────────────────
+[tool.ruff]
+target-version = "py38" # must track requires-python
+line-length = 88
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "W", # pycodestyle
+    "F", # pyflakes
+    "I", # isort
+    "UP", # pyupgrade
+    "B", # flake8-bugbear
+    "SIM", # flake8-simplify
+    "RUF", # ruff-specific
+    "S", # flake8-bandit
+    "C4", # flake8-comprehensions
+    "RET", # flake8-return
+    "PTH", # flake8-use-pathlib
+    "TC", # flake8-type-checking
+    "FA", # flake8-future-annotations
+]
+ignore = ["E501"] # line length is the formatter's job
+
+[tool.ruff.lint.per-file-ignores]
+# The package's documented mechanic is to shell out to the fastglob binary
+# (no shell involved; executable = $FASTGLOB_BIN or the repo-relative release
+# path; arguments are fsencoded bytes). S603 is a manual-review nudge, not a
+# defect, for this call.
+"fastglob/__init__.py" = ["S603"]
+
+[tool.ruff.format]
+quote-style = "double"
+
+# ── mypy (type checker) ───────────────────────────────────────────────────
+[tool.mypy]
+strict = true
+# mypy 2.x minimum target is 3.10 (measured 2026-08-23: a 3.8 target emits
+# "not supported (must be 3.10 or higher)" and clamps). The 3.8-3.9 syntax
+# floor is enforced by ruff's FA/UP rules at target-version py38 (measured:
+# FA102 flags PEP 585/604 annotations missing the future import).
+python_version = "3.10"
+
+# ── pytest ────────────────────────────────────────────────────────────────
+[tool.pytest.ini_options]
+# Canonical runner: `python tests/test_package.py` (Makefile `make test`).
+# Note (measured 2026-08-23): pytest's configfile discovery walks from the
+# TEST ARGS (repo-root tests/), so this section governs pytest runs whose
+# args live under python/; the CI quality job passes --cov explicitly.
+testpaths = ["../tests"]
+addopts = "-ra -q --strict-markers --tb=short"
+
+# ── coverage ──────────────────────────────────────────────────────────────
+[tool.coverage.run]
+source = ["fastglob"] # resolved relative to python/ (the package root)
+
+[tool.coverage.report]
+fail_under = 80
+show_missing = true