trailrunner

What it is and what it does

trailrunner is a lightweight library for discovering files in a project directory while respecting .gitignore rules, and then running arbitrary functions on those files in parallel. It exposes three main functions: walk() to list files in a path tree, run() to execute a function on a list of paths using a process pool, and walk_and_run() to combine both operations. The library is designed for developer tools like linters and formatters that need to batch-process project files in a predictable, .gitignore-aware manner.

The package depends only on pathspec for .gitignore parsing and uses Python's built-in multiprocessing for parallelism. It is classified as Production/Stable but has been dormant since March 2023, with no recent active maintenance. Installation is straightforward with minimal dependencies, making it a low-friction addition to a project.

Use it for:

• Implement a linter or code formatter that discovers and processes all project files while skipping ignored paths.
• Batch-process files in parallel for tasks like syntax validation or metadata extraction across a codebase.
• Build a developer tool that walks a project tree and applies a function to each file, respecting project-level .gitignore rules.
• Parallelize file operations (e.g., checksumming, transformation) across many files in a single call.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Walk filesystem paths while respecting .gitignore rules, and execute functions on found files using a process pool for parallelism.

Yes, for developer tools and batch file processing. The package is stable, has minimal dependencies, and solves a specific problem well. The dormant maintenance status is not a concern for a mature, narrow-scope utility with no known vulnerabilities. Install it if you need .gitignore-aware file discovery with built-in parallelism; skip it if you need active maintenance or ongoing feature development.

Install

trailrunner on PyPI

pip install trailrunner

uv add trailrunner

poetry add trailrunner

Installing trailrunner

Before you install

Low install friction; depends only on pathspec. Dormant maintenance status (last release March 2023, last commit July 2024) means no active development, but the package is classified as Production/Stable and has seen no recent changes to suggest instability.

License in practice

MIT license (permissive); you may use, modify, and distribute this package freely in commercial and private projects with minimal restrictions.

Quickstart

from pathlib import Path
from trailrunner import walk, run, walk_and_run

# Walk a directory respecting .gitignore
files = walk(Path('.'))

# Run a function on each path in parallel
results = run(files, str)

# Or walk and run in one call
results = walk_and_run([Path('.')], str)

Requires Python 3.7 or newer.

Verify before relying

• Whether the process pool size is configurable or uses a default based on system CPU count.
• Performance characteristics when walking very large directory trees.
• Behavior when .gitignore files are nested at multiple levels in the tree.

Package facts

Evidence: trailrunner-1.4.0-py3-none-any.whl

Tags

More Utilities packages