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.
- 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.
- 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.
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:
- __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 fromconcurrent.futures.ProcessPoolExecutor
. Ignored ifDEFAULT_EXECUTOR
is set, or executor_factory is passed.context (BaseContext | None) –
multiprocessing
context used by the default process pool executor. Ignored ifDEFAULT_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.
- 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.
- 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.
- 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, andTrailrunner.run()
for how functions are run for each gathered path.
- 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.
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 bygitignore()
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
.