793 lines
22 KiB
Python
793 lines
22 KiB
Python
"""
|
|
This module provides utility methods for dealing with path-specs.
|
|
"""
|
|
|
|
import os
|
|
import os.path
|
|
import pathlib
|
|
import posixpath
|
|
import stat
|
|
import sys
|
|
import warnings
|
|
from collections.abc import (
|
|
Collection as CollectionType,
|
|
Iterable as IterableType)
|
|
from dataclasses import (
|
|
dataclass)
|
|
from os import (
|
|
PathLike)
|
|
from typing import (
|
|
Any,
|
|
AnyStr,
|
|
Callable, # Replaced by `collections.abc.Callable` in 3.9.
|
|
Collection, # Replaced by `collections.abc.Collection` in 3.9.
|
|
Dict, # Replaced by `dict` in 3.9.
|
|
Generic,
|
|
Iterable, # Replaced by `collections.abc.Iterable` in 3.9.
|
|
Iterator, # Replaced by `collections.abc.Iterator` in 3.9.
|
|
List, # Replaced by `list` in 3.9.
|
|
Optional, # Replaced by `X | None` in 3.10.
|
|
Sequence, # Replaced by `collections.abc.Sequence` in 3.9.
|
|
Set, # Replaced by `set` in 3.9.
|
|
Tuple, # Replaced by `tuple` in 3.9.
|
|
TypeVar,
|
|
Union) # Replaced by `X | Y` in 3.10.
|
|
|
|
from .pattern import (
|
|
Pattern)
|
|
|
|
if sys.version_info >= (3, 9):
|
|
StrPath = Union[str, PathLike[str]]
|
|
else:
|
|
StrPath = Union[str, PathLike]
|
|
|
|
TStrPath = TypeVar("TStrPath", bound=StrPath)
|
|
"""
|
|
Type variable for :class:`str` or :class:`os.PathLike`.
|
|
"""
|
|
|
|
NORMALIZE_PATH_SEPS = [
|
|
__sep
|
|
for __sep in [os.sep, os.altsep]
|
|
if __sep and __sep != posixpath.sep
|
|
]
|
|
"""
|
|
*NORMALIZE_PATH_SEPS* (:class:`list` of :class:`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
|
|
:data:`os.sep` and :data:`os.altsep`.
|
|
"""
|
|
|
|
_registered_patterns = {}
|
|
"""
|
|
*_registered_patterns* (:class:`dict`) maps a name (:class:`str`) to the
|
|
registered pattern factory (:class:`~collections.abc.Callable`).
|
|
"""
|
|
|
|
|
|
def append_dir_sep(path: pathlib.Path) -> str:
|
|
"""
|
|
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* (:class:`pathlib.Path`) is the path to use.
|
|
|
|
Returns the path (:class:`str`).
|
|
"""
|
|
str_path = str(path)
|
|
if path.is_dir():
|
|
str_path += os.sep
|
|
|
|
return str_path
|
|
|
|
|
|
def check_match_file(
|
|
patterns: Iterable[Tuple[int, Pattern]],
|
|
file: str,
|
|
) -> Tuple[Optional[bool], Optional[int]]:
|
|
"""
|
|
Check the file against the patterns.
|
|
|
|
*patterns* (:class:`~collections.abc.Iterable`) yields each indexed pattern
|
|
(:class:`tuple`) which contains the pattern index (:class:`int`) and actual
|
|
pattern (:class:`~pathspec.pattern.Pattern`).
|
|
|
|
*file* (:class:`str`) is the normalized file path to be matched
|
|
against *patterns*.
|
|
|
|
Returns a :class:`tuple` containing whether to include *file* (:class:`bool`
|
|
or :data:`None`), and the index of the last matched pattern (:class:`int` or
|
|
:data:`None`).
|
|
"""
|
|
out_include: Optional[bool] = None
|
|
out_index: Optional[int] = None
|
|
for index, pattern in patterns:
|
|
if pattern.include is not None and pattern.match_file(file) is not None:
|
|
out_include = pattern.include
|
|
out_index = index
|
|
|
|
return out_include, out_index
|
|
|
|
|
|
def detailed_match_files(
|
|
patterns: Iterable[Pattern],
|
|
files: Iterable[str],
|
|
all_matches: Optional[bool] = None,
|
|
) -> Dict[str, 'MatchDetail']:
|
|
"""
|
|
Matches the files to the patterns, and returns which patterns matched
|
|
the files.
|
|
|
|
*patterns* (:class:`~collections.abc.Iterable` of :class:`~pathspec.pattern.Pattern`)
|
|
contains the patterns to use.
|
|
|
|
*files* (:class:`~collections.abc.Iterable` of :class:`str`) contains
|
|
the normalized file paths to be matched against *patterns*.
|
|
|
|
*all_matches* (:class:`bool` or :data:`None`) is whether to return all
|
|
matches patterns (:data:`True`), or only the last matched pattern
|
|
(:data:`False`). Default is :data:`None` for :data:`False`.
|
|
|
|
Returns the matched files (:class:`dict`) which maps each matched file
|
|
(:class:`str`) to the patterns that matched in order (:class:`.MatchDetail`).
|
|
"""
|
|
all_files = files if isinstance(files, CollectionType) else list(files)
|
|
return_files = {}
|
|
for pattern in patterns:
|
|
if pattern.include is not None:
|
|
result_files = pattern.match(all_files) # TODO: Replace with `.match_file()`.
|
|
if pattern.include:
|
|
# Add files and record pattern.
|
|
for result_file in result_files:
|
|
if result_file in return_files:
|
|
if all_matches:
|
|
return_files[result_file].patterns.append(pattern)
|
|
else:
|
|
return_files[result_file].patterns[0] = pattern
|
|
else:
|
|
return_files[result_file] = MatchDetail([pattern])
|
|
|
|
else:
|
|
# Remove files.
|
|
for file in result_files:
|
|
del return_files[file]
|
|
|
|
return return_files
|
|
|
|
|
|
def _filter_check_patterns(
|
|
patterns: Iterable[Pattern],
|
|
) -> List[Tuple[int, Pattern]]:
|
|
"""
|
|
Filters out null-patterns.
|
|
|
|
*patterns* (:class:`Iterable` of :class:`.Pattern`) contains the
|
|
patterns.
|
|
|
|
Returns a :class:`list` containing each indexed pattern (:class:`tuple`) which
|
|
contains the pattern index (:class:`int`) and the actual pattern
|
|
(:class:`~pathspec.pattern.Pattern`).
|
|
"""
|
|
return [
|
|
(__index, __pat)
|
|
for __index, __pat in enumerate(patterns)
|
|
if __pat.include is not None
|
|
]
|
|
|
|
|
|
def _is_iterable(value: Any) -> bool:
|
|
"""
|
|
Check whether the value is an iterable (excludes strings).
|
|
|
|
*value* is the value to check,
|
|
|
|
Returns whether *value* is a iterable (:class:`bool`).
|
|
"""
|
|
return isinstance(value, IterableType) and not isinstance(value, (str, bytes))
|
|
|
|
|
|
def iter_tree_entries(
|
|
root: StrPath,
|
|
on_error: Optional[Callable[[OSError], None]] = None,
|
|
follow_links: Optional[bool] = None,
|
|
) -> Iterator['TreeEntry']:
|
|
"""
|
|
Walks the specified directory for all files and directories.
|
|
|
|
*root* (:class:`str` or :class:`os.PathLike`) is the root directory to
|
|
search.
|
|
|
|
*on_error* (:class:`~collections.abc.Callable` or :data:`None`)
|
|
optionally is the error handler for file-system exceptions. It will be
|
|
called with the exception (:exc:`OSError`). Reraise the exception to
|
|
abort the walk. Default is :data:`None` to ignore file-system
|
|
exceptions.
|
|
|
|
*follow_links* (:class:`bool` or :data:`None`) optionally is whether
|
|
to walk symbolic links that resolve to directories. Default is
|
|
:data:`None` for :data:`True`.
|
|
|
|
Raises :exc:`RecursionError` if recursion is detected.
|
|
|
|
Returns an :class:`~collections.abc.Iterator` yielding each file or
|
|
directory entry (:class:`.TreeEntry`) relative to *root*.
|
|
"""
|
|
if on_error is not None and not callable(on_error):
|
|
raise TypeError(f"on_error:{on_error!r} is not callable.")
|
|
|
|
if follow_links is None:
|
|
follow_links = True
|
|
|
|
yield from _iter_tree_entries_next(os.path.abspath(root), '', {}, on_error, follow_links)
|
|
|
|
|
|
def _iter_tree_entries_next(
|
|
root_full: str,
|
|
dir_rel: str,
|
|
memo: Dict[str, str],
|
|
on_error: Callable[[OSError], None],
|
|
follow_links: bool,
|
|
) -> Iterator['TreeEntry']:
|
|
"""
|
|
Scan the directory for all descendant files.
|
|
|
|
*root_full* (:class:`str`) the absolute path to the root directory.
|
|
|
|
*dir_rel* (:class:`str`) the path to the directory to scan relative to
|
|
*root_full*.
|
|
|
|
*memo* (:class:`dict`) keeps track of ancestor directories
|
|
encountered. Maps each ancestor real path (:class:`str`) to relative
|
|
path (:class:`str`).
|
|
|
|
*on_error* (:class:`~collections.abc.Callable` or :data:`None`)
|
|
optionally is the error handler for file-system exceptions.
|
|
|
|
*follow_links* (:class:`bool`) is whether to walk symbolic links that
|
|
resolve to directories.
|
|
|
|
Yields each entry (:class:`.TreeEntry`).
|
|
"""
|
|
dir_full = os.path.join(root_full, dir_rel)
|
|
dir_real = os.path.realpath(dir_full)
|
|
|
|
# Remember each encountered ancestor directory and its canonical
|
|
# (real) path. If a canonical path is encountered more than once,
|
|
# recursion has occurred.
|
|
if dir_real not in memo:
|
|
memo[dir_real] = dir_rel
|
|
else:
|
|
raise RecursionError(real_path=dir_real, first_path=memo[dir_real], second_path=dir_rel)
|
|
|
|
with os.scandir(dir_full) as scan_iter:
|
|
node_ent: os.DirEntry
|
|
for node_ent in scan_iter:
|
|
node_rel = os.path.join(dir_rel, node_ent.name)
|
|
|
|
# Inspect child node.
|
|
try:
|
|
node_lstat = node_ent.stat(follow_symlinks=False)
|
|
except OSError as e:
|
|
if on_error is not None:
|
|
on_error(e)
|
|
continue
|
|
|
|
if node_ent.is_symlink():
|
|
# Child node is a link, inspect the target node.
|
|
try:
|
|
node_stat = node_ent.stat()
|
|
except OSError as e:
|
|
if on_error is not None:
|
|
on_error(e)
|
|
continue
|
|
else:
|
|
node_stat = node_lstat
|
|
|
|
if node_ent.is_dir(follow_symlinks=follow_links):
|
|
# Child node is a directory, recurse into it and yield its
|
|
# descendant files.
|
|
yield TreeEntry(node_ent.name, node_rel, node_lstat, node_stat)
|
|
|
|
yield from _iter_tree_entries_next(root_full, node_rel, memo, on_error, follow_links)
|
|
|
|
elif node_ent.is_file() or node_ent.is_symlink():
|
|
# Child node is either a file or an unfollowed link, yield it.
|
|
yield TreeEntry(node_ent.name, node_rel, node_lstat, node_stat)
|
|
|
|
# NOTE: Make sure to remove the canonical (real) path of the directory
|
|
# from the ancestors memo once we are done with it. This allows the
|
|
# same directory to appear multiple times. If this is not done, the
|
|
# second occurrence of the directory will be incorrectly interpreted
|
|
# as a recursion. See <https://github.com/cpburnz/python-path-specification/pull/7>.
|
|
del memo[dir_real]
|
|
|
|
|
|
def iter_tree_files(
|
|
root: StrPath,
|
|
on_error: Optional[Callable[[OSError], None]] = None,
|
|
follow_links: Optional[bool] = None,
|
|
) -> Iterator[str]:
|
|
"""
|
|
Walks the specified directory for all files.
|
|
|
|
*root* (:class:`str` or :class:`os.PathLike`) is the root directory to
|
|
search for files.
|
|
|
|
*on_error* (:class:`~collections.abc.Callable` or :data:`None`)
|
|
optionally is the error handler for file-system exceptions. It will be
|
|
called with the exception (:exc:`OSError`). Reraise the exception to
|
|
abort the walk. Default is :data:`None` to ignore file-system
|
|
exceptions.
|
|
|
|
*follow_links* (:class:`bool` or :data:`None`) optionally is whether
|
|
to walk symbolic links that resolve to directories. Default is
|
|
:data:`None` for :data:`True`.
|
|
|
|
Raises :exc:`RecursionError` if recursion is detected.
|
|
|
|
Returns an :class:`~collections.abc.Iterator` yielding the path to
|
|
each file (:class:`str`) relative to *root*.
|
|
"""
|
|
for entry in iter_tree_entries(root, on_error=on_error, follow_links=follow_links):
|
|
if not entry.is_dir(follow_links):
|
|
yield entry.path
|
|
|
|
|
|
def iter_tree(root, on_error=None, follow_links=None):
|
|
"""
|
|
DEPRECATED: The :func:`.iter_tree` function is an alias for the
|
|
:func:`.iter_tree_files` function.
|
|
"""
|
|
warnings.warn((
|
|
"util.iter_tree() is deprecated. Use util.iter_tree_files() instead."
|
|
), DeprecationWarning, stacklevel=2)
|
|
return iter_tree_files(root, on_error=on_error, follow_links=follow_links)
|
|
|
|
|
|
def lookup_pattern(name: str) -> Callable[[AnyStr], Pattern]:
|
|
"""
|
|
Lookups a registered pattern factory by name.
|
|
|
|
*name* (:class:`str`) is the name of the pattern factory.
|
|
|
|
Returns the registered pattern factory (:class:`~collections.abc.Callable`).
|
|
If no pattern factory is registered, raises :exc:`KeyError`.
|
|
"""
|
|
return _registered_patterns[name]
|
|
|
|
|
|
def match_file(patterns: Iterable[Pattern], file: str) -> bool:
|
|
"""
|
|
Matches the file to the patterns.
|
|
|
|
*patterns* (:class:`~collections.abc.Iterable` of :class:`~pathspec.pattern.Pattern`)
|
|
contains the patterns to use.
|
|
|
|
*file* (:class:`str`) is the normalized file path to be matched
|
|
against *patterns*.
|
|
|
|
Returns :data:`True` if *file* matched; otherwise, :data:`False`.
|
|
"""
|
|
matched = False
|
|
for pattern in patterns:
|
|
if pattern.include is not None and pattern.match_file(file) is not None:
|
|
matched = pattern.include
|
|
|
|
return matched
|
|
|
|
|
|
def match_files(
|
|
patterns: Iterable[Pattern],
|
|
files: Iterable[str],
|
|
) -> Set[str]:
|
|
"""
|
|
DEPRECATED: This is an old function no longer used. Use the
|
|
:func:`~pathspec.util.match_file` function with a loop for better results.
|
|
|
|
Matches the files to the patterns.
|
|
|
|
*patterns* (:class:`~collections.abc.Iterable` of :class:`~pathspec.pattern.Pattern`)
|
|
contains the patterns to use.
|
|
|
|
*files* (:class:`~collections.abc.Iterable` of :class:`str`) contains
|
|
the normalized file paths to be matched against *patterns*.
|
|
|
|
Returns the matched files (:class:`set` of :class:`str`).
|
|
"""
|
|
warnings.warn((
|
|
f"{__name__}.match_files() is deprecated. Use {__name__}.match_file() with "
|
|
f"a loop for better results."
|
|
), DeprecationWarning, stacklevel=2)
|
|
|
|
use_patterns = [__pat for __pat in patterns if __pat.include is not None]
|
|
|
|
return_files = set()
|
|
for file in files:
|
|
if match_file(use_patterns, file):
|
|
return_files.add(file)
|
|
|
|
return return_files
|
|
|
|
|
|
def normalize_file(
|
|
file: StrPath,
|
|
separators: Optional[Collection[str]] = None,
|
|
) -> str:
|
|
"""
|
|
Normalizes the file path to use the POSIX path separator (i.e.,
|
|
``"/"``), and make the paths relative (remove leading ``"/"``).
|
|
|
|
*file* (:class:`str` or :class:`os.PathLike`) is the file path.
|
|
|
|
*separators* (:class:`~collections.abc.Collection` of :class:`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 (:class:`str`).
|
|
"""
|
|
# Normalize path separators.
|
|
if separators is None:
|
|
separators = NORMALIZE_PATH_SEPS
|
|
|
|
# Convert path object to string.
|
|
norm_file: str = os.fspath(file)
|
|
|
|
for sep in separators:
|
|
norm_file = norm_file.replace(sep, posixpath.sep)
|
|
|
|
if norm_file.startswith('/'):
|
|
# Make path relative.
|
|
norm_file = norm_file[1:]
|
|
|
|
elif norm_file.startswith('./'):
|
|
# Remove current directory prefix.
|
|
norm_file = norm_file[2:]
|
|
|
|
return norm_file
|
|
|
|
|
|
def normalize_files(
|
|
files: Iterable[StrPath],
|
|
separators: Optional[Collection[str]] = None,
|
|
) -> Dict[str, List[StrPath]]:
|
|
"""
|
|
DEPRECATED: This function is no longer used. Use the :func:`.normalize_file`
|
|
function with a loop for better results.
|
|
|
|
Normalizes the file paths to use the POSIX path separator.
|
|
|
|
*files* (:class:`~collections.abc.Iterable` of :class:`str` or
|
|
:class:`os.PathLike`) contains the file paths to be normalized.
|
|
|
|
*separators* (:class:`~collections.abc.Collection` of :class:`str`; or
|
|
:data:`None`) optionally contains the path separators to normalize.
|
|
See :func:`normalize_file` for more information.
|
|
|
|
Returns a :class:`dict` mapping each normalized file path (:class:`str`)
|
|
to the original file paths (:class:`list` of :class:`str` or
|
|
:class:`os.PathLike`).
|
|
"""
|
|
warnings.warn((
|
|
"util.normalize_files() is deprecated. Use util.normalize_file() "
|
|
"with a loop for better results."
|
|
), DeprecationWarning, stacklevel=2)
|
|
|
|
norm_files = {}
|
|
for path in files:
|
|
norm_file = normalize_file(path, separators=separators)
|
|
if norm_file in norm_files:
|
|
norm_files[norm_file].append(path)
|
|
else:
|
|
norm_files[norm_file] = [path]
|
|
|
|
return norm_files
|
|
|
|
|
|
def register_pattern(
|
|
name: str,
|
|
pattern_factory: Callable[[AnyStr], Pattern],
|
|
override: Optional[bool] = None,
|
|
) -> None:
|
|
"""
|
|
Registers the specified pattern factory.
|
|
|
|
*name* (:class:`str`) is the name to register the pattern factory
|
|
under.
|
|
|
|
*pattern_factory* (:class:`~collections.abc.Callable`) is used to
|
|
compile patterns. It must accept an uncompiled pattern (:class:`str`)
|
|
and return the compiled pattern (:class:`.Pattern`).
|
|
|
|
*override* (:class:`bool` or :data:`None`) optionally is whether to
|
|
allow overriding an already registered pattern under the same name
|
|
(:data:`True`), instead of raising an :exc:`AlreadyRegisteredError`
|
|
(:data:`False`). Default is :data:`None` for :data:`False`.
|
|
"""
|
|
if not isinstance(name, str):
|
|
raise TypeError(f"name:{name!r} is not a string.")
|
|
|
|
if not callable(pattern_factory):
|
|
raise TypeError(f"pattern_factory:{pattern_factory!r} is not callable.")
|
|
|
|
if name in _registered_patterns and not override:
|
|
raise AlreadyRegisteredError(name, _registered_patterns[name])
|
|
|
|
_registered_patterns[name] = pattern_factory
|
|
|
|
|
|
class AlreadyRegisteredError(Exception):
|
|
"""
|
|
The :exc:`AlreadyRegisteredError` exception is raised when a pattern
|
|
factory is registered under a name already in use.
|
|
"""
|
|
|
|
def __init__(
|
|
self,
|
|
name: str,
|
|
pattern_factory: Callable[[AnyStr], Pattern],
|
|
) -> None:
|
|
"""
|
|
Initializes the :exc:`AlreadyRegisteredError` instance.
|
|
|
|
*name* (:class:`str`) is the name of the registered pattern.
|
|
|
|
*pattern_factory* (:class:`~collections.abc.Callable`) is the
|
|
registered pattern factory.
|
|
"""
|
|
super(AlreadyRegisteredError, self).__init__(name, pattern_factory)
|
|
|
|
@property
|
|
def message(self) -> str:
|
|
"""
|
|
*message* (:class:`str`) is the error message.
|
|
"""
|
|
return "{name!r} is already registered for pattern factory:{pattern_factory!r}.".format(
|
|
name=self.name,
|
|
pattern_factory=self.pattern_factory,
|
|
)
|
|
|
|
@property
|
|
def name(self) -> str:
|
|
"""
|
|
*name* (:class:`str`) is the name of the registered pattern.
|
|
"""
|
|
return self.args[0]
|
|
|
|
@property
|
|
def pattern_factory(self) -> Callable[[AnyStr], Pattern]:
|
|
"""
|
|
*pattern_factory* (:class:`~collections.abc.Callable`) is the
|
|
registered pattern factory.
|
|
"""
|
|
return self.args[1]
|
|
|
|
|
|
class RecursionError(Exception):
|
|
"""
|
|
The :exc:`RecursionError` exception is raised when recursion is
|
|
detected.
|
|
"""
|
|
|
|
def __init__(
|
|
self,
|
|
real_path: str,
|
|
first_path: str,
|
|
second_path: str,
|
|
) -> None:
|
|
"""
|
|
Initializes the :exc:`RecursionError` instance.
|
|
|
|
*real_path* (:class:`str`) is the real path that recursion was
|
|
encountered on.
|
|
|
|
*first_path* (:class:`str`) is the first path encountered for
|
|
*real_path*.
|
|
|
|
*second_path* (:class:`str`) is the second path encountered for
|
|
*real_path*.
|
|
"""
|
|
super(RecursionError, self).__init__(real_path, first_path, second_path)
|
|
|
|
@property
|
|
def first_path(self) -> str:
|
|
"""
|
|
*first_path* (:class:`str`) is the first path encountered for
|
|
:attr:`self.real_path <RecursionError.real_path>`.
|
|
"""
|
|
return self.args[1]
|
|
|
|
@property
|
|
def message(self) -> str:
|
|
"""
|
|
*message* (:class:`str`) is the error message.
|
|
"""
|
|
return "Real path {real!r} was encountered at {first!r} and then {second!r}.".format(
|
|
real=self.real_path,
|
|
first=self.first_path,
|
|
second=self.second_path,
|
|
)
|
|
|
|
@property
|
|
def real_path(self) -> str:
|
|
"""
|
|
*real_path* (:class:`str`) is the real path that recursion was
|
|
encountered on.
|
|
"""
|
|
return self.args[0]
|
|
|
|
@property
|
|
def second_path(self) -> str:
|
|
"""
|
|
*second_path* (:class:`str`) is the second path encountered for
|
|
:attr:`self.real_path <RecursionError.real_path>`.
|
|
"""
|
|
return self.args[2]
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class CheckResult(Generic[TStrPath]):
|
|
"""
|
|
The :class:`CheckResult` class contains information about the file and which
|
|
pattern matched it.
|
|
"""
|
|
|
|
# Make the class dict-less.
|
|
__slots__ = (
|
|
'file',
|
|
'include',
|
|
'index',
|
|
)
|
|
|
|
file: TStrPath
|
|
"""
|
|
*file* (:class:`str` or :class:`os.PathLike`) is the file path.
|
|
"""
|
|
|
|
include: Optional[bool]
|
|
"""
|
|
*include* (:class:`bool` or :data:`None`) is whether to include or exclude the
|
|
file. If :data:`None`, no pattern matched.
|
|
"""
|
|
|
|
index: Optional[int]
|
|
"""
|
|
*index* (:class:`int` or :data:`None`) is the index of the last pattern that
|
|
matched. If :data:`None`, no pattern matched.
|
|
"""
|
|
|
|
|
|
class MatchDetail(object):
|
|
"""
|
|
The :class:`.MatchDetail` class contains information about
|
|
"""
|
|
|
|
# Make the class dict-less.
|
|
__slots__ = ('patterns',)
|
|
|
|
def __init__(self, patterns: Sequence[Pattern]) -> None:
|
|
"""
|
|
Initialize the :class:`.MatchDetail` instance.
|
|
|
|
*patterns* (:class:`~collections.abc.Sequence` of :class:`~pathspec.pattern.Pattern`)
|
|
contains the patterns that matched the file in the order they were
|
|
encountered.
|
|
"""
|
|
|
|
self.patterns = patterns
|
|
"""
|
|
*patterns* (:class:`~collections.abc.Sequence` of :class:`~pathspec.pattern.Pattern`)
|
|
contains the patterns that matched the file in the order they were
|
|
encountered.
|
|
"""
|
|
|
|
|
|
class TreeEntry(object):
|
|
"""
|
|
The :class:`.TreeEntry` class contains information about a file-system
|
|
entry.
|
|
"""
|
|
|
|
# Make the class dict-less.
|
|
__slots__ = ('_lstat', 'name', 'path', '_stat')
|
|
|
|
def __init__(
|
|
self,
|
|
name: str,
|
|
path: str,
|
|
lstat: os.stat_result,
|
|
stat: os.stat_result,
|
|
) -> None:
|
|
"""
|
|
Initialize the :class:`.TreeEntry` instance.
|
|
|
|
*name* (:class:`str`) is the base name of the entry.
|
|
|
|
*path* (:class:`str`) is the relative path of the entry.
|
|
|
|
*lstat* (:class:`os.stat_result`) is the stat result of the direct
|
|
entry.
|
|
|
|
*stat* (:class:`os.stat_result`) is the stat result of the entry,
|
|
potentially linked.
|
|
"""
|
|
|
|
self._lstat: os.stat_result = lstat
|
|
"""
|
|
*_lstat* (:class:`os.stat_result`) is the stat result of the direct
|
|
entry.
|
|
"""
|
|
|
|
self.name: str = name
|
|
"""
|
|
*name* (:class:`str`) is the base name of the entry.
|
|
"""
|
|
|
|
self.path: str = path
|
|
"""
|
|
*path* (:class:`str`) is the path of the entry.
|
|
"""
|
|
|
|
self._stat: os.stat_result = stat
|
|
"""
|
|
*_stat* (:class:`os.stat_result`) is the stat result of the linked
|
|
entry.
|
|
"""
|
|
|
|
def is_dir(self, follow_links: Optional[bool] = None) -> bool:
|
|
"""
|
|
Get whether the entry is a directory.
|
|
|
|
*follow_links* (:class:`bool` or :data:`None`) is whether to follow
|
|
symbolic links. If this is :data:`True`, a symlink to a directory
|
|
will result in :data:`True`. Default is :data:`None` for :data:`True`.
|
|
|
|
Returns whether the entry is a directory (:class:`bool`).
|
|
"""
|
|
if follow_links is None:
|
|
follow_links = True
|
|
|
|
node_stat = self._stat if follow_links else self._lstat
|
|
return stat.S_ISDIR(node_stat.st_mode)
|
|
|
|
def is_file(self, follow_links: Optional[bool] = None) -> bool:
|
|
"""
|
|
Get whether the entry is a regular file.
|
|
|
|
*follow_links* (:class:`bool` or :data:`None`) is whether to follow
|
|
symbolic links. If this is :data:`True`, a symlink to a regular file
|
|
will result in :data:`True`. Default is :data:`None` for :data:`True`.
|
|
|
|
Returns whether the entry is a regular file (:class:`bool`).
|
|
"""
|
|
if follow_links is None:
|
|
follow_links = True
|
|
|
|
node_stat = self._stat if follow_links else self._lstat
|
|
return stat.S_ISREG(node_stat.st_mode)
|
|
|
|
def is_symlink(self) -> bool:
|
|
"""
|
|
Returns whether the entry is a symbolic link (:class:`bool`).
|
|
"""
|
|
return stat.S_ISLNK(self._lstat.st_mode)
|
|
|
|
def stat(self, follow_links: Optional[bool] = None) -> os.stat_result:
|
|
"""
|
|
Get the cached stat result for the entry.
|
|
|
|
*follow_links* (:class:`bool` or :data:`None`) is whether to follow
|
|
symbolic links. If this is :data:`True`, the stat result of the
|
|
linked file will be returned. Default is :data:`None` for :data:`True`.
|
|
|
|
Returns that stat result (:class:`os.stat_result`).
|
|
"""
|
|
if follow_links is None:
|
|
follow_links = True
|
|
|
|
return self._stat if follow_links else self._lstat
|