init

.venv/lib/python3.8/site-packages/pathspec/pathspec.py

@@ -0,0 +1,243 @@
+# encoding: utf-8
+"""
+This module provides an object oriented interface for pattern matching
+of files.
+"""
+
+try:
+	from typing import (
+		Any,
+		AnyStr,
+		Callable,
+		Iterable,
+		Iterator,
+		Optional,
+		Text,
+		Union)
+except ImportError:
+	pass
+
+try:
+	# Python 3.6+ type hints.
+	from os import PathLike
+	from typing import Collection
+except ImportError:
+	pass
+
+from . import util
+from .compat import (
+	CollectionType,
+	iterkeys,
+	izip_longest,
+	string_types)
+from .pattern import Pattern
+from .util import TreeEntry
+
+
+class PathSpec(object):
+	"""
+	The :class:`PathSpec` class is a wrapper around a list of compiled
+	:class:`.Pattern` instances.
+	"""
+
+	def __init__(self, patterns):
+		# type: (Iterable[Pattern]) -> None
+		"""
+		Initializes the :class:`PathSpec` instance.
+
+		*patterns* (:class:`~collections.abc.Collection` or :class:`~collections.abc.Iterable`)
+		yields each compiled pattern (:class:`.Pattern`).
+		"""
+
+		self.patterns = patterns if isinstance(patterns, CollectionType) else list(patterns)
+		"""
+		*patterns* (:class:`~collections.abc.Collection` of :class:`.Pattern`)
+		contains the compiled patterns.
+		"""
+
+	def __eq__(self, other):
+		# type: (PathSpec) -> bool
+		"""
+		Tests the equality of this path-spec with *other* (:class:`PathSpec`)
+		by comparing their :attr:`~PathSpec.patterns` attributes.
+		"""
+		if isinstance(other, PathSpec):
+			paired_patterns = izip_longest(self.patterns, other.patterns)
+			return all(a == b for a, b in paired_patterns)
+		else:
+			return NotImplemented
+
+	def __len__(self):
+		"""
+		Returns the number of compiled patterns this path-spec contains
+		(:class:`int`).
+		"""
+		return len(self.patterns)
+
+	def __add__(self, other):
+		# type: (PathSpec) -> PathSpec
+		"""
+		Combines the :attr:`Pathspec.patterns` patterns from two
+		:class:`PathSpec` instances.
+		"""
+		if isinstance(other, PathSpec):
+			return PathSpec(self.patterns + other.patterns)
+		else:
+			return NotImplemented
+
+	def __iadd__(self, other):
+		# type: (PathSpec) -> PathSpec
+		"""
+		Adds the :attr:`Pathspec.patterns` patterns from one :class:`PathSpec`
+		instance to this instance.
+		"""
+		if isinstance(other, PathSpec):
+			self.patterns += other.patterns
+			return self
+		else:
+			return NotImplemented
+
+	@classmethod
+	def from_lines(cls, pattern_factory, lines):
+		# type: (Union[Text, Callable[[AnyStr], Pattern]], Iterable[AnyStr]) -> PathSpec
+		"""
+		Compiles the pattern lines.
+
+		*pattern_factory* can be either the name of a registered pattern
+		factory (:class:`str`), or a :class:`~collections.abc.Callable` used
+		to compile patterns. It must accept an uncompiled pattern (:class:`str`)
+		and return the compiled pattern (:class:`.Pattern`).
+
+		*lines* (:class:`~collections.abc.Iterable`) yields each uncompiled
+		pattern (:class:`str`). This simply has to yield each line so it can
+		be a :class:`file` (e.g., from :func:`open` or :class:`io.StringIO`)
+		or the result from :meth:`str.splitlines`.
+
+		Returns the :class:`PathSpec` instance.
+		"""
+		if isinstance(pattern_factory, string_types):
+			pattern_factory = util.lookup_pattern(pattern_factory)
+		if not callable(pattern_factory):
+			raise TypeError("pattern_factory:{!r} is not callable.".format(pattern_factory))
+
+		if not util._is_iterable(lines):
+			raise TypeError("lines:{!r} is not an iterable.".format(lines))
+
+		patterns = [pattern_factory(line) for line in lines if line]
+		return cls(patterns)
+
+	def match_file(self, file, separators=None):
+		# type: (Union[Text, PathLike], Optional[Collection[Text]]) -> bool
+		"""
+		Matches the file to this path-spec.
+
+		*file* (:class:`str` or :class:`~pathlib.PurePath`) is the file path
+		to be matched against :attr:`self.patterns <PathSpec.patterns>`.
+
+		*separators* (:class:`~collections.abc.Collection` of :class:`str`)
+		optionally contains the path separators to normalize. See
+		:func:`~pathspec.util.normalize_file` for more information.
+
+		Returns :data:`True` if *file* matched; otherwise, :data:`False`.
+		"""
+		norm_file = util.normalize_file(file, separators=separators)
+		return util.match_file(self.patterns, norm_file)
+
+	def match_entries(self, entries, separators=None):
+		# type: (Iterable[TreeEntry], Optional[Collection[Text]]) -> Iterator[TreeEntry]
+		"""
+		Matches the entries to this path-spec.
+
+		*entries* (:class:`~collections.abc.Iterable` of :class:`~util.TreeEntry`)
+		contains the entries to be matched against :attr:`self.patterns <PathSpec.patterns>`.
+
+		*separators* (:class:`~collections.abc.Collection` of :class:`str`;
+		or :data:`None`) optionally contains the path separators to
+		normalize. See :func:`~pathspec.util.normalize_file` for more
+		information.
+
+		Returns the matched entries (:class:`~collections.abc.Iterator` of
+		:class:`~util.TreeEntry`).
+		"""
+		if not util._is_iterable(entries):
+			raise TypeError("entries:{!r} is not an iterable.".format(entries))
+
+		entry_map = util._normalize_entries(entries, separators=separators)
+		match_paths = util.match_files(self.patterns, iterkeys(entry_map))
+		for path in match_paths:
+			yield entry_map[path]
+
+	def match_files(self, files, separators=None):
+		# type: (Iterable[Union[Text, PathLike]], Optional[Collection[Text]]) -> Iterator[Union[Text, PathLike]]
+		"""
+		Matches the files to this path-spec.
+
+		*files* (:class:`~collections.abc.Iterable` of :class:`str; or
+		:class:`pathlib.PurePath`) contains the file paths to be matched
+		against :attr:`self.patterns <PathSpec.patterns>`.
+
+		*separators* (:class:`~collections.abc.Collection` of :class:`str`;
+		or :data:`None`) optionally contains the path separators to
+		normalize. See :func:`~pathspec.util.normalize_file` for more
+		information.
+
+		Returns the matched files (:class:`~collections.abc.Iterator` of
+		:class:`str` or :class:`pathlib.PurePath`).
+		"""
+		if not util._is_iterable(files):
+			raise TypeError("files:{!r} is not an iterable.".format(files))
+
+		file_map = util.normalize_files(files, separators=separators)
+		matched_files = util.match_files(self.patterns, iterkeys(file_map))
+		for norm_file in matched_files:
+			for orig_file in file_map[norm_file]:
+				yield orig_file
+
+	def match_tree_entries(self, root, on_error=None, follow_links=None):
+		# type: (Text, Optional[Callable], Optional[bool]) -> Iterator[TreeEntry]
+		"""
+		Walks the specified root path for all files and matches them to this
+		path-spec.
+
+		*root* (:class:`str`; or :class:`pathlib.PurePath`) is the root
+		directory to search.
+
+		*on_error* (:class:`~collections.abc.Callable` or :data:`None`)
+		optionally is the error handler for file-system exceptions. See
+		:func:`~pathspec.util.iter_tree_entries` for more information.
+
+		*follow_links* (:class:`bool` or :data:`None`) optionally is whether
+		to walk symbolic links that resolve to directories. See
+		:func:`~pathspec.util.iter_tree_files` for more information.
+
+		Returns the matched files (:class:`~collections.abc.Iterator` of
+		:class:`.TreeEntry`).
+		"""
+		entries = util.iter_tree_entries(root, on_error=on_error, follow_links=follow_links)
+		return self.match_entries(entries)
+
+	def match_tree_files(self, root, on_error=None, follow_links=None):
+		# type: (Text, Optional[Callable], Optional[bool]) -> Iterator[Text]
+		"""
+		Walks the specified root path for all files and matches them to this
+		path-spec.
+
+		*root* (:class:`str`; or :class:`pathlib.PurePath`) 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. See
+		:func:`~pathspec.util.iter_tree_files` for more information.
+
+		*follow_links* (:class:`bool` or :data:`None`) optionally is whether
+		to walk symbolic links that resolve to directories. See
+		:func:`~pathspec.util.iter_tree_files` for more information.
+
+		Returns the matched files (:class:`~collections.abc.Iterable` of
+		:class:`str`).
+		"""
+		files = util.iter_tree_files(root, on_error=on_error, follow_links=follow_links)
+		return self.match_files(files)
+
+	# Alias `match_tree_files()` as `match_tree()`.
+	match_tree = match_tree_files