[config.git] / djavu-asus / elpy / rpc-venv / lib / python3.11 / site-packages / pathspec / pathspec.py

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

from collections.abc import (
	Collection as CollectionType)
from itertools import (
	zip_longest)
from typing import (
	AnyStr,
	Callable,
	Collection,
	Iterable,
	Iterator,
	Optional,
	Type,
	TypeVar,
	Union)

from . import util
from .pattern import (
	Pattern)
from .util import (
	StrPath,
	TreeEntry,
	_filter_patterns,
	_is_iterable,
	match_file,
	normalize_file)

Self = TypeVar("Self", bound="PathSpec")
"""
:class:`PathSpec` self type hint to support Python v<3.11 using PEP 673
recommendation.
"""


class PathSpec(object):
	"""
	The :class:`PathSpec` class is a wrapper around a list of compiled
	:class:`.Pattern` instances.
	"""

	def __init__(self, patterns: 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: object) -> 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 = zip_longest(self.patterns, other.patterns)
			return all(a == b for a, b in paired_patterns)
		else:
			return NotImplemented

	def __len__(self) -> int:
		"""
		Returns the number of compiled patterns this path-spec contains
		(:class:`int`).
		"""
		return len(self.patterns)

	def __add__(self: Self, other: "PathSpec") -> Self:
		"""
		Combines the :attr:`Pathspec.patterns` patterns from two
		:class:`PathSpec` instances.
		"""
		if isinstance(other, PathSpec):
			return self.__class__(self.patterns + other.patterns)
		else:
			return NotImplemented

	def __iadd__(self: Self, other: "PathSpec") -> Self:
		"""
		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: Type[Self],
		pattern_factory: Union[str, Callable[[AnyStr], Pattern]],
		lines: Iterable[AnyStr],
	) -> Self:
		"""
		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 that it can be a
		:class:`io.TextIOBase` (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, str):
			pattern_factory = util.lookup_pattern(pattern_factory)

		if not callable(pattern_factory):
			raise TypeError(f"pattern_factory:{pattern_factory!r} is not callable.")

		if not _is_iterable(lines):
			raise TypeError(f"lines:{lines!r} is not an iterable.")

		patterns = [pattern_factory(line) for line in lines if line]
		return cls(patterns)

	def match_entries(
		self,
		entries: Iterable[TreeEntry],
		separators: Optional[Collection[str]] = None,
		*,
		negate: Optional[bool] = None,
	) -> 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.

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

		Returns the matched entries (:class:`~collections.abc.Iterator` of
		:class:`~util.TreeEntry`).
		"""
		if not _is_iterable(entries):
			raise TypeError(f"entries:{entries!r} is not an iterable.")

		use_patterns = _filter_patterns(self.patterns)
		for entry in entries:
			norm_file = normalize_file(entry.path, separators)
			is_match = self._match_file(use_patterns, norm_file)

			if negate:
				is_match = not is_match

			if is_match:
				yield entry

	# Match files using the `match_file()` utility function. Subclasses may
	# override this method as an instance method. It does not have to be a static
	# method.
	_match_file = staticmethod(match_file)

	def match_file(
		self,
		file: StrPath,
		separators: Optional[Collection[str]] = None,
	) -> bool:
		"""
		Matches the file to this path-spec.

		*file* (:class:`str` or :class:`os.PathLike[str]`) 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 self._match_file(self.patterns, norm_file)

	def match_files(
		self,
		files: Iterable[StrPath],
		separators: Optional[Collection[str]] = None,
		*,
		negate: Optional[bool] = None,
	) -> Iterator[StrPath]:
		"""
		Matches the files to this path-spec.

		*files* (:class:`~collections.abc.Iterable` of :class:`str` or
		:class:`os.PathLike[str]`) 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.

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

		Returns the matched files (:class:`~collections.abc.Iterator` of
		:class:`str` or :class:`os.PathLike[str]`).
		"""
		if not _is_iterable(files):
			raise TypeError(f"files:{files!r} is not an iterable.")

		use_patterns = _filter_patterns(self.patterns)
		for orig_file in files:
			norm_file = normalize_file(orig_file, separators)
			is_match = self._match_file(use_patterns, norm_file)

			if negate:
				is_match = not is_match

			if is_match:
				yield orig_file

	def match_tree_entries(
		self,
		root: StrPath,
		on_error: Optional[Callable] = None,
		follow_links: Optional[bool] = None,
		*,
		negate: Optional[bool] = None,
	) -> Iterator[TreeEntry]:
		"""
		Walks the specified root path for all files and matches them to this
		path-spec.

		*root* (:class:`str` or :class:`os.PathLike[str]`) 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.

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

		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)
		yield from self.match_entries(entries, negate=negate)

	def match_tree_files(
		self,
		root: StrPath,
		on_error: Optional[Callable] = None,
		follow_links: Optional[bool] = None,
		*,
		negate: Optional[bool] = None,
	) -> Iterator[str]:
		"""
		Walks the specified root path for all files and matches them to this
		path-spec.

		*root* (:class:`str` or :class:`os.PathLike[str]`) 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.

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

		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)
		yield from self.match_files(files, negate=negate)

	# Alias `match_tree_files()` as `match_tree()` for backward compatibility
	# before v0.3.2.
	match_tree = match_tree_files
Commit	Line	Data
53e6db90 DC	1	"""
	2	This module provides an object oriented interface for pattern matching of files.
	3	"""
	4
	5	from collections.abc import (
	6	Collection as CollectionType)
	7	from itertools import (
	8	zip_longest)
	9	from typing import (
	10	AnyStr,
	11	Callable,
	12	Collection,
	13	Iterable,
	14	Iterator,
	15	Optional,
	16	Type,
	17	TypeVar,
	18	Union)
	19
	20	from . import util
	21	from .pattern import (
	22	Pattern)
	23	from .util import (
	24	StrPath,
	25	TreeEntry,
	26	_filter_patterns,
	27	_is_iterable,
	28	match_file,
	29	normalize_file)
	30
	31	Self = TypeVar("Self", bound="PathSpec")
	32	"""
	33	:class:`PathSpec` self type hint to support Python v<3.11 using PEP 673
	34	recommendation.
	35	"""
	36
	37
	38	class PathSpec(object):
	39	"""
	40	The :class:`PathSpec` class is a wrapper around a list of compiled
	41	:class:`.Pattern` instances.
	42	"""
	43
	44	def __init__(self, patterns: Iterable[Pattern]) -> None:
	45	"""
	46	Initializes the :class:`PathSpec` instance.
	47
	48	patterns (:class:`~collections.abc.Collection` or :class:`~collections.abc.Iterable`)
	49	yields each compiled pattern (:class:`.Pattern`).
	50	"""
	51
	52	self.patterns = patterns if isinstance(patterns, CollectionType) else list(patterns)
	53	"""
	54	patterns (:class:`~collections.abc.Collection` of :class:`.Pattern`)
	55	contains the compiled patterns.
	56	"""
	57
	58	def __eq__(self, other: object) -> bool:
	59	"""
	60	Tests the equality of this path-spec with other (:class:`PathSpec`)
	61	by comparing their :attr:`~PathSpec.patterns` attributes.
	62	"""
	63	if isinstance(other, PathSpec):
	64	paired_patterns = zip_longest(self.patterns, other.patterns)
65	return all(a == b for a, b in paired_patterns)
66	else:
67	return NotImplemented
68
69	def __len__(self) -> int:
70	"""
71	Returns the number of compiled patterns this path-spec contains
72	(:class:`int`).
73	"""
74	return len(self.patterns)
75
76	def __add__(self: Self, other: "PathSpec") -> Self:
77	"""
78	Combines the :attr:`Pathspec.patterns` patterns from two
79	:class:`PathSpec` instances.
80	"""
81	if isinstance(other, PathSpec):
82	return self.__class__(self.patterns + other.patterns)
83	else:
84	return NotImplemented
85
86	def __iadd__(self: Self, other: "PathSpec") -> Self:
87	"""
88	Adds the :attr:`Pathspec.patterns` patterns from one :class:`PathSpec`
89	instance to this instance.
90	"""
91	if isinstance(other, PathSpec):
92	self.patterns += other.patterns
93	return self
94	else:
95	return NotImplemented
96
97	@classmethod
98	def from_lines(
99	cls: Type[Self],
100	pattern_factory: Union[str, Callable[[AnyStr], Pattern]],
101	lines: Iterable[AnyStr],
102	) -> Self:
103	"""
104	Compiles the pattern lines.
105
106	pattern_factory can be either the name of a registered pattern factory
107	(:class:`str`), or a :class:`~collections.abc.Callable` used to compile
108	patterns. It must accept an uncompiled pattern (:class:`str`) and return the
109	compiled pattern (:class:`.Pattern`).
110
111	lines (:class:`~collections.abc.Iterable`) yields each uncompiled pattern
112	(:class:`str`). This simply has to yield each line so that it can be a
113	:class:`io.TextIOBase` (e.g., from :func:`open` or :class:`io.StringIO`) or
114	the result from :meth:`str.splitlines`.
115
116	Returns the :class:`PathSpec` instance.
117	"""
118	if isinstance(pattern_factory, str):
119	pattern_factory = util.lookup_pattern(pattern_factory)
120
121	if not callable(pattern_factory):
122	raise TypeError(f"pattern_factory:{pattern_factory!r} is not callable.")
123
124	if not _is_iterable(lines):
125	raise TypeError(f"lines:{lines!r} is not an iterable.")
126
127	patterns = [pattern_factory(line) for line in lines if line]
128	return cls(patterns)
129
130	def match_entries(
131	self,
132	entries: Iterable[TreeEntry],
133	separators: Optional[Collection[str]] = None,
134	*,
135	negate: Optional[bool] = None,
136	) -> Iterator[TreeEntry]:
137	"""
138	Matches the entries to this path-spec.
139
140	entries (:class:`~collections.abc.Iterable` of :class:`~util.TreeEntry`)
141	contains the entries to be matched against :attr:`self.patterns <PathSpec.patterns>`.
142
143	separators (:class:`~collections.abc.Collection` of :class:`str`; or
144	:data:`None`) optionally contains the path separators to normalize. See
145	:func:`~pathspec.util.normalize_file` for more information.
146
147	negate (:class:`bool` or :data:`None`) is whether to negate the match
148	results of the patterns. If :data:`True`, a pattern matching a file will
149	exclude the file rather than include it. Default is :data:`None` for
150	:data:`False`.
151
152	Returns the matched entries (:class:`~collections.abc.Iterator` of
153	:class:`~util.TreeEntry`).
154	"""
155	if not _is_iterable(entries):
156	raise TypeError(f"entries:{entries!r} is not an iterable.")
157
158	use_patterns = _filter_patterns(self.patterns)
159	for entry in entries:
160	norm_file = normalize_file(entry.path, separators)
161	is_match = self._match_file(use_patterns, norm_file)
162
163	if negate:
164	is_match = not is_match
165
166	if is_match:
167	yield entry
168
169	# Match files using the `match_file()` utility function. Subclasses may
170	# override this method as an instance method. It does not have to be a static
171	# method.
172	_match_file = staticmethod(match_file)
173
174	def match_file(
175	self,
176	file: StrPath,
177	separators: Optional[Collection[str]] = None,
178	) -> bool:
179	"""
180	Matches the file to this path-spec.
181
182	file (:class:`str` or :class:`os.PathLike[str]`) is the file path to be
183	matched against :attr:`self.patterns <PathSpec.patterns>`.
184
185	separators (:class:`~collections.abc.Collection` of :class:`str`)
186	optionally contains the path separators to normalize. See
187	:func:`~pathspec.util.normalize_file` for more information.
188
189	Returns :data:`True` if file matched; otherwise, :data:`False`.
190	"""
191	norm_file = util.normalize_file(file, separators=separators)
192	return self._match_file(self.patterns, norm_file)
193
194	def match_files(
195	self,
196	files: Iterable[StrPath],
197	separators: Optional[Collection[str]] = None,
198	*,
199	negate: Optional[bool] = None,
200	) -> Iterator[StrPath]:
201	"""
202	Matches the files to this path-spec.
203
204	files (:class:`~collections.abc.Iterable` of :class:`str` or
205	:class:`os.PathLike[str]`) contains the file paths to be matched against
206	:attr:`self.patterns <PathSpec.patterns>`.
207
208	separators (:class:`~collections.abc.Collection` of :class:`str`; or
209	:data:`None`) optionally contains the path separators to normalize. See
210	:func:`~pathspec.util.normalize_file` for more information.
211
212	negate (:class:`bool` or :data:`None`) is whether to negate the match
213	results of the patterns. If :data:`True`, a pattern matching a file will
214	exclude the file rather than include it. Default is :data:`None` for
215	:data:`False`.
216
217	Returns the matched files (:class:`~collections.abc.Iterator` of
218	:class:`str` or :class:`os.PathLike[str]`).
219	"""
220	if not _is_iterable(files):
221	raise TypeError(f"files:{files!r} is not an iterable.")
222
223	use_patterns = _filter_patterns(self.patterns)
224	for orig_file in files:
225	norm_file = normalize_file(orig_file, separators)
226	is_match = self._match_file(use_patterns, norm_file)
227
228	if negate:
229	is_match = not is_match
230
231	if is_match:
232	yield orig_file
233
234	def match_tree_entries(
235	self,
236	root: StrPath,
237	on_error: Optional[Callable] = None,
238	follow_links: Optional[bool] = None,
239	*,
240	negate: Optional[bool] = None,
241	) -> Iterator[TreeEntry]:
242	"""
243	Walks the specified root path for all files and matches them to this
244	path-spec.
245
246	root (:class:`str` or :class:`os.PathLike[str]`) is the root directory to
247	search.
248
249	on_error (:class:`~collections.abc.Callable` or :data:`None`) optionally
250	is the error handler for file-system exceptions. See
251	:func:`~pathspec.util.iter_tree_entries` for more information.
252
253	follow_links (:class:`bool` or :data:`None`) optionally is whether to walk
254	symbolic links that resolve to directories. See
255	:func:`~pathspec.util.iter_tree_files` for more information.
256
257	negate (:class:`bool` or :data:`None`) is whether to negate the match
258	results of the patterns. If :data:`True`, a pattern matching a file will
259	exclude the file rather than include it. Default is :data:`None` for
260	:data:`False`.
261
262	Returns the matched files (:class:`~collections.abc.Iterator` of
263	:class:`.TreeEntry`).
264	"""
265	entries = util.iter_tree_entries(root, on_error=on_error, follow_links=follow_links)
266	yield from self.match_entries(entries, negate=negate)
267
268	def match_tree_files(
269	self,
270	root: StrPath,
271	on_error: Optional[Callable] = None,
272	follow_links: Optional[bool] = None,
273	*,
274	negate: Optional[bool] = None,
275	) -> Iterator[str]:
276	"""
277	Walks the specified root path for all files and matches them to this
278	path-spec.
279
280	root (:class:`str` or :class:`os.PathLike[str]`) is the root directory to
281	search for files.
282
283	on_error (:class:`~collections.abc.Callable` or :data:`None`) optionally
284	is the error handler for file-system exceptions. See
285	:func:`~pathspec.util.iter_tree_files` for more information.
286
287	follow_links (:class:`bool` or :data:`None`) optionally is whether to walk
288	symbolic links that resolve to directories. See
289	:func:`~pathspec.util.iter_tree_files` for more information.
290
291	negate (:class:`bool` or :data:`None`) is whether to negate the match
292	results of the patterns. If :data:`True`, a pattern matching a file will
293	exclude the file rather than include it. Default is :data:`None` for
294	:data:`False`.
295
296	Returns the matched files (:class:`~collections.abc.Iterable` of
297	:class:`str`).
298	"""
299	files = util.iter_tree_files(root, on_error=on_error, follow_links=follow_links)
300	yield from self.match_files(files, negate=negate)
301
302	# Alias `match_tree_files()` as `match_tree()` for backward compatibility
303	# before v0.3.2.
304	match_tree = match_tree_files