rignore

rignore is a Python module that provides high-performance file system traversal by wrapping the Rust ignore crate through PyO3. It offers an efficient way to walk directories while respecting .gitignore, global git ignores, git excludes, and custom ignore patterns.

The library exposes a simple walk() function and a Walker iterator that yield file paths, backed by the same battle-tested traversal engine used by ripgrep. It combines Rust’s speed and memory efficiency with an easy-to-use, fully type-hinted Python API.

What You Get

• A fast walk() function returning an iterator of file paths
• A Walker class for reusable, configurable traversal
• Respect for .gitignore, global git ignore, git exclude, and parent ignores
• Customizable ignore patterns, overrides, depth, filesize, and symlink handling
• A fully type-hinted API via a bundled .pyi stub

Common Use Cases

• Quickly listing project files while skipping ignored and hidden paths
• Building file-indexing or search tools that honor .gitignore rules
• Filtering large directory trees with custom ignore patterns at speed
• Replacing slow pure-Python os.walk loops in build and tooling scripts

Under The Hood

Architecture rignore is a thin, focused PyO3 extension. The entire binding lives in src/lib.rs (~260 lines), which exposes a Walker class and a walk() function to Python. Internally it configures an ignore::WalkBuilder from the Rust ignore crate with the many optional flags (ignore_hidden, read_git_ignore, additional_ignores, overrides, max_depth, follow_links, and a Python callback for per-entry exclusion) and iterates entries lazily, yielding paths back to Python. The crate is compiled as a cdylib extension module, so traversal runs entirely in native Rust while presenting a Pythonic iterator.

Tech Stack Rust (edition 2021) with pyo3 0.29 and the ignore 0.4 crate as the two dependencies, built into a Python wheel with maturin. The Python side has zero runtime dependencies and supports Python 3.8+ on both CPython and PyPy. A Nix flake and uv lockfile support reproducible development.

Code Quality The project ships a typed rignore.pyi stub mirroring the native signatures and includes a Python test suite (tests/test_walk.py). Releases are automated via autopub and a CHANGELOG is maintained. The codebase is small and single-purpose, which keeps it easy to audit; development is active with frequent releases.

API Design The API is intentionally tiny: call rignore.walk(path, ...) and iterate the result, or construct a Walker directly for reuse. All of the many tuning parameters are optional keyword arguments with sensible None defaults, and a should_exclude_entry callback lets you filter entries in Python. The bundled type stub makes editor autocomplete and static checking work out of the box.