API

pathspec

The pathspec package provides pattern matching for file paths. So far this only includes Git’s wildmatch pattern matching (the style used for “.gitignore” files).

The following classes are imported and made available from the root of the pathspec package:

• pathspec.gitignore.GitIgnoreSpec

• pathspec.pathspec.PathSpec

• pathspec.pattern.Pattern

• pathspec.pattern.RegexPattern

• pathspec.util.RecursionError

The following functions are also imported:

• pathspec.util.lookup_pattern()

The following deprecated functions are also imported to maintain backward compatibility:

• pathspec.util.iter_tree() which is an alias for pathspec.util.iter_tree_files().

• pathspec.util.match_files()

pathspec.pathspec

This module provides an object oriented interface for pattern matching of files.

class pathspec.pathspec.PathSpec(patterns)

Bases: object

The PathSpec class is a wrapper around a list of compiled Pattern instances.

__init__(patterns)

Initializes the PathSpec instance.

patterns (Collection or Iterable) yields each compiled pattern (Pattern).

patterns

patterns (Collection of Pattern) contains the compiled patterns.

__eq__(other)

Tests the equality of this path-spec with other (PathSpec) by comparing their patterns attributes.

__len__()

Returns the number of compiled patterns this path-spec contains (int).

check_file(file, separators=None)

Check the files against this path-spec.

file (str or os.PathLike) is the file path to be matched against self.patterns.

separators (Collection of str; or None) optionally contains the path separators to normalize. See normalize_file() for more information.

Returns the file check result (CheckResult).

check_files(files, separators=None)

Check the files against this path-spec.

files (Iterable of str or os.PathLike) contains the file paths to be checked against self.patterns.

separators (Collection of str; or None) optionally contains the path separators to normalize. See normalize_file() for more information.

Returns an Iterator yielding each file check result (CheckResult).

check_tree_files(root, on_error=None, follow_links=None)

Walks the specified root path for all files and checks them against this path-spec.

root (str or os.PathLike) is the root directory to search for files.

on_error (Callable or None) optionally is the error handler for file-system exceptions. It will be called with the exception (OSError). Reraise the exception to abort the walk. Default is None to ignore file-system exceptions.

follow_links (bool or None) optionally is whether to walk symbolic links that resolve to directories. Default is None for True.

negate (bool or None) is whether to negate the match results of the patterns. If True, a pattern matching a file will exclude the file rather than include it. Default is None for False.

Returns an Iterator yielding each file check result (CheckResult).

classmethod from_lines(pattern_factory, lines)

Compiles the pattern lines.

pattern_factory can be either the name of a registered pattern factory (str), or a Callable used to compile patterns. It must accept an uncompiled pattern (str) and return the compiled pattern (Pattern).

lines (Iterable) yields each uncompiled pattern (str). This simply has to yield each line so that it can be a io.TextIOBase (e.g., from open() or io.StringIO) or the result from str.splitlines().

Returns the PathSpec instance.

match_entries(entries, separators=None, *, negate=None)

Matches the entries to this path-spec.

entries (Iterable of TreeEntry) contains the entries to be matched against self.patterns.

separators (Collection of str; or None) optionally contains the path separators to normalize. See normalize_file() for more information.

negate (bool or None) is whether to negate the match results of the patterns. If True, a pattern matching a file will exclude the file rather than include it. Default is None for False.

Returns the matched entries (Iterator of TreeEntry).

match_file(file, separators=None)

Matches the file to this path-spec.

file (str or os.PathLike) is the file path to be matched against self.patterns.

separators (Collection of str) optionally contains the path separators to normalize. See normalize_file() for more information.

Returns True if file matched; otherwise, False.

match_files(files, separators=None, *, negate=None)

Matches the files to this path-spec.

files (Iterable of str or os.PathLike) contains the file paths to be matched against self.patterns.

separators (Collection of str; or None) optionally contains the path separators to normalize. See normalize_file() for more information.

negate (bool or None) is whether to negate the match results of the patterns. If True, a pattern matching a file will exclude the file rather than include it. Default is None for False.

Returns the matched files (Iterator of str or os.PathLike).

match_tree_entries(root, on_error=None, follow_links=None, *, negate=None)

Walks the specified root path for all files and matches them to this path-spec.

root (str or os.PathLike) is the root directory to search.

on_error (Callable or None) optionally is the error handler for file-system exceptions. It will be called with the exception (OSError). Reraise the exception to abort the walk. Default is None to ignore file-system exceptions.

follow_links (bool or None) optionally is whether to walk symbolic links that resolve to directories. Default is None for True.

negate (bool or None) is whether to negate the match results of the patterns. If True, a pattern matching a file will exclude the file rather than include it. Default is None for False.

Returns the matched files (Iterator of TreeEntry).

match_tree_files(root, on_error=None, follow_links=None, *, negate=None)

Walks the specified root path for all files and matches them to this path-spec.

root (str or os.PathLike) is the root directory to search for files.

on_error (Callable or None) optionally is the error handler for file-system exceptions. It will be called with the exception (OSError). Reraise the exception to abort the walk. Default is None to ignore file-system exceptions.

follow_links (bool or None) optionally is whether to walk symbolic links that resolve to directories. Default is None for True.

negate (bool or None) is whether to negate the match results of the patterns. If True, a pattern matching a file will exclude the file rather than include it. Default is None for False.

Returns the matched files (Iterable of str).

match_tree(root, on_error=None, follow_links=None, *, negate=None)

Walks the specified root path for all files and matches them to this path-spec.

root (str or os.PathLike) is the root directory to search for files.

on_error (Callable or None) optionally is the error handler for file-system exceptions. It will be called with the exception (OSError). Reraise the exception to abort the walk. Default is None to ignore file-system exceptions.

follow_links (bool or None) optionally is whether to walk symbolic links that resolve to directories. Default is None for True.

negate (bool or None) is whether to negate the match results of the patterns. If True, a pattern matching a file will exclude the file rather than include it. Default is None for False.

Returns the matched files (Iterable of str).

pathspec.gitignore

This module provides GitIgnoreSpec which replicates .gitignore behavior.

class pathspec.gitignore.GitIgnoreSpec(patterns)

Bases: PathSpec

The GitIgnoreSpec class extends pathspec.pathspec.PathSpec to replicate .gitignore behavior.

__eq__(other)

Tests the equality of this gitignore-spec with other (GitIgnoreSpec) by comparing their Pattern attributes. A non-GitIgnoreSpec will not compare equal.

classmethod from_lines(lines, pattern_factory=None)

Compiles the pattern lines.

lines (Iterable) yields each uncompiled pattern (str). This simply has to yield each line so it can be a io.TextIOBase (e.g., from open() or io.StringIO) or the result from str.splitlines().

pattern_factory can be None, the name of a registered pattern factory (str), or a Callable used to compile patterns. The callable must accept an uncompiled pattern (str) and return the compiled pattern (pathspec.pattern.Pattern). Default is None for GitWildMatchPattern).

Returns the GitIgnoreSpec instance.

pathspec.pattern

This module provides the base definition for patterns.

class pathspec.pattern.Pattern(include)

Bases: object

The Pattern class is the abstract definition of a pattern.

__init__(include)

Initializes the Pattern instance.

include (bool or None) is whether the matched files should be included (True), excluded (False), or is a null-operation (None).

include

include (bool or None) is whether the matched files should be included (True), excluded (False), or is a null-operation (None).

match(files)

DEPRECATED: This method is no longer used and has been replaced by match_file(). Use the match_file() method with a loop for similar results.

Matches this pattern against the specified files.

files (Iterable of str) contains each file relative to the root directory (e.g., "relative/path/to/file").

Returns an Iterable yielding each matched file path (str).

match_file(file)

Matches this pattern against the specified file.

file (str) is the normalized file path to match against.

Returns the match result if file matched; otherwise, None.

class pathspec.pattern.RegexPattern(pattern, include=None)

Bases: Pattern

The RegexPattern class is an implementation of a pattern using regular expressions.

__init__(pattern, include=None)

Initializes the RegexPattern instance.

pattern (str, bytes, re.Pattern, or None) is the pattern to compile into a regular expression.

include (bool or None) must be None unless pattern is a precompiled regular expression (re.Pattern) in which case it is whether matched files should be included (True), excluded (False), or is a null operation (None).

Note

Subclasses do not need to support the include parameter.

pattern

pattern (str, bytes, re.Pattern, or None) is the uncompiled, input pattern. This is for reference.

regex

regex (re.Pattern) is the regular expression for the pattern.

__eq__(other)

Tests the equality of this regex pattern with other (RegexPattern) by comparing their include and regex attributes.

match_file(file)

Matches this pattern against the specified file.

file (str) contains each file relative to the root directory (e.g., “relative/path/to/file”).

Returns the match result (RegexMatchResult) if file matched; otherwise, None.

classmethod pattern_to_regex(pattern)

Convert the pattern into an uncompiled regular expression.

pattern (str) is the pattern to convert into a regular expression.

Returns the uncompiled regular expression (str or None), and whether matched files should be included (True), excluded (False), or is a null-operation (None).

Note

The default implementation simply returns pattern and True.

class pathspec.pattern.RegexMatchResult(match)

Bases: object

The RegexMatchResult data class is used to return information about the matched regular expression.

__init__(match)

match

match (re.Match) is the regex match result.

pathspec.patterns.gitwildmatch

This module implements Git’s wildmatch pattern matching which itself is derived from Rsync’s wildmatch. Git uses wildmatch for its “.gitignore” files.

class pathspec.patterns.gitwildmatch.GitWildMatchPattern(pattern, include=None)

Bases: RegexPattern

The GitWildMatchPattern class represents a compiled Git wildmatch pattern.

classmethod pattern_to_regex(pattern)

Convert the pattern into a regular expression.

pattern (str or bytes) is the pattern to convert into a regular expression.

Returns the uncompiled regular expression (str, bytes, or None); and whether matched files should be included (True), excluded (False), or if it is a null-operation (None).

static escape(s)

Escape special characters in the given string.

s (str or bytes) a filename or a string that you want to escape, usually before adding it to a “.gitignore”.

Returns the escaped string (str or bytes).

include

include (bool or None) is whether the matched files should be included (True), excluded (False), or is a null-operation (None).

match(files)

DEPRECATED: This method is no longer used and has been replaced by match_file(). Use the match_file() method with a loop for similar results.

Matches this pattern against the specified files.

files (Iterable of str) contains each file relative to the root directory (e.g., "relative/path/to/file").

Returns an Iterable yielding each matched file path (str).

match_file(file)

Matches this pattern against the specified file.

file (str) contains each file relative to the root directory (e.g., “relative/path/to/file”).

Returns the match result (RegexMatchResult) if file matched; otherwise, None.

pattern

pattern (str, bytes, re.Pattern, or None) is the uncompiled, input pattern. This is for reference.

regex

regex (re.Pattern) is the regular expression for the pattern.

pathspec.util

This module provides utility methods for dealing with path-specs.

class pathspec.util.TStrPath

Type variable for str or os.PathLike.

alias of TypeVar(‘TStrPath’, bound=Union[str, PathLike[str]])

pathspec.util.NORMALIZE_PATH_SEPS = []

NORMALIZE_PATH_SEPS (list of str) contains the path separators that need to be normalized to the POSIX separator for the current operating system. The separators are determined by examining os.sep and os.altsep.

pathspec.util.append_dir_sep(path)

Appends the path separator to the path if the path is a directory. This can be used to aid in distinguishing between directories and files on the file-system by relying on the presence of a trailing path separator.

path (pathlib.Path) is the path to use.

Returns the path (str).

pathspec.util.check_match_file(patterns, file)

Check the file against the patterns.

patterns (Iterable) yields each indexed pattern (tuple) which contains the pattern index (int) and actual pattern (Pattern).

file (str) is the normalized file path to be matched against patterns.

Returns a tuple containing whether to include file (bool or None), and the index of the last matched pattern (int or None).

pathspec.util.detailed_match_files(patterns, files, all_matches=None)

Matches the files to the patterns, and returns which patterns matched the files.

patterns (Iterable of Pattern) contains the patterns to use.

files (Iterable of str) contains the normalized file paths to be matched against patterns.

all_matches (bool or None) is whether to return all matches patterns (True), or only the last matched pattern (False). Default is None for False.

Returns the matched files (dict) which maps each matched file (str) to the patterns that matched in order (MatchDetail).

pathspec.util.iter_tree_entries(root, on_error=None, follow_links=None)

Walks the specified directory for all files and directories.

root (str or os.PathLike) is the root directory to search.

on_error (Callable or None) optionally is the error handler for file-system exceptions. It will be called with the exception (OSError). Reraise the exception to abort the walk. Default is None to ignore file-system exceptions.

follow_links (bool or None) optionally is whether to walk symbolic links that resolve to directories. Default is None for True.

Raises RecursionError if recursion is detected.

Returns an Iterator yielding each file or directory entry (TreeEntry) relative to root.

pathspec.util.iter_tree_files(root, on_error=None, follow_links=None)

Walks the specified directory for all files.

root (str or os.PathLike) is the root directory to search for files.

on_error (Callable or None) optionally is the error handler for file-system exceptions. It will be called with the exception (OSError). Reraise the exception to abort the walk. Default is None to ignore file-system exceptions.

follow_links (bool or None) optionally is whether to walk symbolic links that resolve to directories. Default is None for True.

Raises RecursionError if recursion is detected.

Returns an Iterator yielding the path to each file (str) relative to root.

pathspec.util.iter_tree(root, on_error=None, follow_links=None)

DEPRECATED: The iter_tree() function is an alias for the iter_tree_files() function.

pathspec.util.lookup_pattern(name)

Lookups a registered pattern factory by name.

name (str) is the name of the pattern factory.

Returns the registered pattern factory (Callable). If no pattern factory is registered, raises KeyError.

pathspec.util.match_file(patterns, file)

Matches the file to the patterns.

patterns (Iterable of Pattern) contains the patterns to use.

file (str) is the normalized file path to be matched against patterns.

Returns True if file matched; otherwise, False.

pathspec.util.match_files(patterns, files)

DEPRECATED: This is an old function no longer used. Use the match_file() function with a loop for better results.

Matches the files to the patterns.

patterns (Iterable of Pattern) contains the patterns to use.

files (Iterable of str) contains the normalized file paths to be matched against patterns.

Returns the matched files (set of str).

pathspec.util.normalize_file(file, separators=None)

Normalizes the file path to use the POSIX path separator (i.e., "/"), and make the paths relative (remove leading "/").

file (str or os.PathLike) is the file path.

separators (Collection of str; or None) optionally contains the path separators to normalize. This does not need to include the POSIX path separator ("/"), but including it will not affect the results. Default is None for NORMALIZE_PATH_SEPS. To prevent normalization, pass an empty container (e.g., an empty tuple ()).

Returns the normalized file path (str).

pathspec.util.normalize_files(files, separators=None)

DEPRECATED: This function is no longer used. Use the normalize_file() function with a loop for better results.

Normalizes the file paths to use the POSIX path separator.

files (Iterable of str or os.PathLike) contains the file paths to be normalized.

separators (Collection of str; or None) optionally contains the path separators to normalize. See normalize_file() for more information.

Returns a dict mapping each normalized file path (str) to the original file paths (list of str or os.PathLike).

pathspec.util.register_pattern(name, pattern_factory, override=None)

Registers the specified pattern factory.

name (str) is the name to register the pattern factory under.

pattern_factory (Callable) is used to compile patterns. It must accept an uncompiled pattern (str) and return the compiled pattern (Pattern).

override (bool or None) optionally is whether to allow overriding an already registered pattern under the same name (True), instead of raising an AlreadyRegisteredError (False). Default is None for False.

exception pathspec.util.AlreadyRegisteredError(name, pattern_factory)

Bases: Exception

The AlreadyRegisteredError exception is raised when a pattern factory is registered under a name already in use.

property message

message (str) is the error message.

property name

name (str) is the name of the registered pattern.

property pattern_factory

pattern_factory (Callable) is the registered pattern factory.

exception pathspec.util.RecursionError(real_path, first_path, second_path)

Bases: Exception

The RecursionError exception is raised when recursion is detected.

property first_path

first_path (str) is the first path encountered for self.real_path.

property message

message (str) is the error message.

property real_path

real_path (str) is the real path that recursion was encountered on.

property second_path

second_path (str) is the second path encountered for self.real_path.

class pathspec.util.CheckResult(file, include, index)

Bases: Generic[TStrPath]

The CheckResult class contains information about the file and which pattern matched it.

file

file (str or os.PathLike) is the file path.

include

include (bool or None) is whether to include or exclude the file. If None, no pattern matched.

index

index (int or None) is the index of the last pattern that matched. If None, no pattern matched.

class pathspec.util.MatchDetail(patterns)

Bases: object

The MatchDetail class contains information about

patterns

patterns (Sequence of Pattern) contains the patterns that matched the file in the order they were encountered.

class pathspec.util.TreeEntry(name, path, lstat, stat)

Bases: object

The TreeEntry class contains information about a file-system entry.

name

name (str) is the base name of the entry.

path

path (str) is the path of the entry.

is_dir(follow_links=None)

Get whether the entry is a directory.

follow_links (bool or None) is whether to follow symbolic links. If this is True, a symlink to a directory will result in True. Default is None for True.

Returns whether the entry is a directory (bool).

is_file(follow_links=None)

Get whether the entry is a regular file.

follow_links (bool or None) is whether to follow symbolic links. If this is True, a symlink to a regular file will result in True. Default is None for True.

Returns whether the entry is a regular file (bool).

is_symlink()

Returns whether the entry is a symbolic link (bool).

stat(follow_links=None)

Get the cached stat result for the entry.

follow_links (bool or None) is whether to follow symbolic links. If this is True, the stat result of the linked file will be returned. Default is None for True.

Returns that stat result (os.stat_result).