API Reference

Basic

trailrunner.walk(path, *, excludes=None)

Generate all significant file paths, starting from the given path.

Finds the project root and any associated gitignore. Filters any paths that match a gitignore pattern. Recurses into subdirectories, and otherwise only includes files that match the trailrunner.core.INCLUDE_PATTERN regex.

Optional excludes parameter allows supplying an extra set of paths (or gitignore-style patterns) to exclude from the final results.

Returns a generator that yields each significant file as the tree is walked.

Parameters:

  • path (Path)

  • excludes (List[str] | None)

Return type:

Iterator[Path]

trailrunner.run(paths, func)

Run a given function once for each path, using a process pool for concurrency.

For each path given, func will be called with path as the only argument. To pass any other positional or keyword arguments, use functools.partial.

Results from each path will be returned as a dictionary mapping path to result.

Uses a process pool with “spawned” processes that share no state with the parent process, to enforce consistent behavior on Linux, macOS, and Windows, where forked processes are not possible.

Parameters:
Return type:

Dict[Path, T]

trailrunner.run_iter(paths, func)

Run a given function once for each path, using a process pool for concurrency.

For each path given, func will be called with path as the only argument. To pass any other positional or keyword arguments, use functools.partial.

Each path, and the function result, will be yielded as they are completed.

Uses a process pool with “spawned” processes that share no state with the parent process, to enforce consistent behavior on Linux, macOS, and Windows, where forked processes are not possible.

Parameters:
Return type:

Generator[Tuple[Path, T], None, None]

trailrunner.walk_and_run(paths, func, *, excludes=None)

Walks each path given, and runs the given function on all gathered paths.

See walk() for details on how paths are gathered, and run() for how functions are run for each gathered path.

Parameters:
Return type:

Dict[Path, T]

Advanced

class trailrunner.Trailrunner(*, concurrency=0, context=None, executor_factory=None)

Self-contained Trailrunner instance with configurable multiprocessing semantics.

The basic API functions above are lightweight wrappers calling their respective methods on fresh instances of the Trailrunner class with no arguments.

By default, uses a process pool executor with “spawn” child processes, to enforce consistent behavior when running functions on Linux, macOS, and Windows. This can be overridden for each individual instance by passing an executor factory during initialization.

Parameters:

  • concurrency (int)

  • context (BaseContext | None)

  • executor_factory (Callable[[], Executor] | None)

__init__(*, concurrency=0, context=None, executor_factory=None)
Parameters:

  • concurreny – maximum number of child processes to use for jobs. Values < 1 will use the default concurrency level from concurrent.futures.ProcessPoolExecutor. Ignored if DEFAULT_EXECUTOR is set, or executor_factory is passed.

  • context (BaseContext | None) – multiprocessing context used by the default process pool executor. Ignored if DEFAULT_EXECUTOR is set, or executor_factory is passed.

  • executor_factory (Callable[[], Executor] | None) – Alternative executor factory. Must be a function that takes no arguments, and returns an instance of concurrent.futures.Executor.

  • concurrency (int)

run(paths, func)

Run a given function once for each path, using an executor for concurrency.

For each path given, func will be called with path as the only argument. To pass any other positional or keyword arguments, use functools.partial.

Results from each path will be returned as a dictionary mapping path to result.

Parameters:
Return type:

Dict[Path, T]

run_iter(paths, func)

Run a given function once for each path, using an executor for concurrency.

For each path given, func will be called with path as the only argument. To pass any other positional or keyword arguments, use functools.partial.

Each path, and the function result, will be yielded as they are completed.

Parameters:
Return type:

Generator[Tuple[Path, T], None, None]

walk(path, *, excludes=None)

Generate all significant file paths, starting from the given path.

Finds the project root and any associated gitignore. Filters any paths that match a gitignore pattern. Recurses into subdirectories, and otherwise only includes files that match the trailrunner.core.INCLUDE_PATTERN regex.

Optional excludes parameter allows supplying an extra set of paths (or gitignore-style patterns) to exclude from the final results.

Returns a generator that yields each significant file as the tree is walked.

Parameters:

  • path (Path)

  • excludes (List[str] | None)

Return type:

Iterator[Path]

walk_and_run(paths, func, *, excludes=None)

Walks each path given, and runs the given function on all gathered paths.

See Trailrunner.walk() for details on how paths are gathered, and Trailrunner.run() for how functions are run for each gathered path.

Parameters:
Return type:

Dict[Path, T]

DEFAULT_EXECUTOR: Callable[[], Executor] | None = None

Global override for the default executor, used when executor_factory is not passed to new instances. This is intended primarily for use in unit testing, when it is desirable to force using thread pools by default.

Prefer explicitly passing executor_factory when possible to avoid conflicting behavior with other packages that also use trailrunner.

EXCLUDED: Dict[Path, str] = {}

Utilities

trailrunner.core.INCLUDE_PATTERN: str = '.+\\.pyi?$'

Regex pattern used to match against filenames that should be included in results when recursively walking directories. Any files not matching this regex will be ignored.

trailrunner.core.ROOT_MARKERS: List[Path] = [PosixPath('pyproject.toml'), PosixPath('.git'), PosixPath('.hg')]

List of pathlib.Path objects used to “mark” the root of project. This is used by gitignore() for finding and reading a .gitignore file from the project root of a given path or directory.

trailrunner.core.project_root(path)

Find the project root, looking upward from the given path.

Looks through all parent paths until either the root is reached, or a directory is found that contains any of ROOT_MARKERS.

Parameters:

path (Path)

Return type:

Path

trailrunner.core.gitignore(path)

Generate a PathSpec object for a .gitignore file in the given directory.

If none is found, an empty PathSpec is returned. If the path is not a directory, ValueError is raised.

Parameters:

path (Path)

Return type:

PathSpec