API Reference

trailrunner.walk(path)

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.

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

Parameters

path (pathlib.Path) –

Return type

Iterator[pathlib.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[pathlib.Path, T]

trailrunner.walk_and_run(paths, func)

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[pathlib.Path, T]

core.INCLUDE_PATTERN = '.+\\.pyi?$'
core.ROOT_MARKERS = [PosixPath('pyproject.toml'), PosixPath('.git'), PosixPath('.hg')]
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 trailrunner.core.ROOT_MARKERS.

Parameters

path (pathlib.Path) –

Return type

pathlib.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 (pathlib.Path) –

Return type

pathspec.pathspec.PathSpec