Initial commit: add .gitignore and README

.venv/lib/python3.12/site-packages/pathspec/pattern.py

@@ -0,0 +1,241 @@
+"""
+This module provides the base definition for patterns.
+"""
+from __future__ import annotations
+
+import re
+from collections.abc import (
+	Iterable,
+	Iterator)
+from dataclasses import (
+	dataclass)
+from typing import (
+	Any,
+	Optional,  # Replaced by `X | None` in 3.10.
+	TypeVar,
+	Union)  # Replaced by `X | Y` in 3.10.
+
+from ._typing import (
+	AnyStr,  # Removed in 3.18.
+	deprecated,  # Added in 3.13.
+	override)  # Added in 3.12.
+
+RegexPatternSelf = TypeVar("RegexPatternSelf", bound='RegexPattern')
+"""
+:class:`.RegexPattern` self type hint to support Python v<3.11 using PEP 673
+recommendation.
+"""
+
+class Pattern(object):
+	"""
+	The :class:`Pattern` class is the abstract definition of a pattern.
+	"""
+
+	# Make the class dict-less.
+	__slots__ = (
+		'include',
+	)
+
+	def __init__(self, include: Optional[bool]) -> None:
+		"""
+		Initializes the :class:`Pattern` instance.
+
+		*include* (:class:`bool` or :data:`None`) is whether the matched files
+		should be included (:data:`True`), excluded (:data:`False`), or is a
+		null-operation (:data:`None`).
+		"""
+
+		self.include = include
+		"""
+		*include* (:class:`bool` or :data:`None`) is whether the matched files
+		should be included (:data:`True`), excluded (:data:`False`), or is a
+		null-operation (:data:`None`).
+		"""
+
+	@deprecated((
+		"Pattern.match() is deprecated. Use Pattern.match_file() with a loop for "
+		"similar results."
+	))
+	def match(self, files: Iterable[str]) -> Iterator[str]:
+		"""
+		.. version-deprecated:: 0.10.0
+			This method is no longer used. Use the :meth:`self.match_file <.Pattern.match_file>`
+			method with a loop for similar results.
+
+		Matches this pattern against the specified files.
+
+		*files* (:class:`~collections.abc.Iterable` of :class:`str`) contains each
+		file relative to the root directory.
+
+		Returns an :class:`~collections.abc.Iterable` yielding each matched file
+		path (:class:`str`).
+		"""
+		for file in files:
+			if self.match_file(file) is not None:
+				yield file
+
+	def match_file(self, file: str) -> Optional[Any]:
+		"""
+		Matches this pattern against the specified file.
+
+		*file* (:class:`str`) is the normalized file path to match against.
+
+		Returns the match result if *file* matched; otherwise, :data:`None`.
+		"""
+		raise NotImplementedError((
+			"{cls.__module__}.{cls.__qualname__} must override match_file()."
+		).format(cls=self.__class__))
+
+
+class RegexPattern(Pattern):
+	"""
+	The :class:`RegexPattern` class is an implementation of a pattern using
+	regular expressions.
+	"""
+
+	# Keep the class dict-less.
+	__slots__ = (
+		'pattern',
+		'regex',
+	)
+
+	def __init__(
+		self,
+		pattern: Union[AnyStr, re.Pattern, None],
+		include: Optional[bool] = None,
+	) -> None:
+		"""
+		Initializes the :class:`RegexPattern` instance.
+
+		*pattern* (:class:`str`, :class:`bytes`, :class:`re.Pattern`, or
+		:data:`None`) is the pattern to compile into a regular expression.
+
+		*include* (:class:`bool` or :data:`None`) must be :data:`None` unless
+		*pattern* is a precompiled regular expression (:class:`re.Pattern`) in which
+		case it is whether matched files should be included (:data:`True`), excluded
+		(:data:`False`), or is a null operation (:data:`None`).
+
+			.. note:: Subclasses do not need to support the *include* parameter.
+		"""
+
+		if isinstance(pattern, (str, bytes)):
+			assert include is None, (
+				f"include:{include!r} must be null when pattern:{pattern!r} is a string."
+			)
+			regex, include = self.pattern_to_regex(pattern)
+			# NOTE: Make sure to allow a null regular expression to be
+			# returned for a null-operation.
+			if include is not None:
+				regex = re.compile(regex)
+
+		elif pattern is not None and hasattr(pattern, 'match'):
+			# Assume pattern is a precompiled regular expression.
+			# - NOTE: Used specified *include*.
+			regex = pattern
+
+		elif pattern is None:
+			# NOTE: Make sure to allow a null pattern to be passed for a
+			# null-operation.
+			assert include is None, (
+				f"include:{include!r} must be null when pattern:{pattern!r} is null."
+			)
+			regex = None
+
+		else:
+			raise TypeError(f"pattern:{pattern!r} is not a string, re.Pattern, or None.")
+
+		super(RegexPattern, self).__init__(include)
+
+		self.pattern: Union[AnyStr, re.Pattern, None] = pattern
+		"""
+		*pattern* (:class:`str`, :class:`bytes`, :class:`re.Pattern`, or
+		:data:`None`) is the uncompiled, input pattern. This is for reference.
+		"""
+
+		self.regex: Optional[re.Pattern] = regex
+		"""
+		*regex* (:class:`re.Pattern` or :data:`None`) is the compiled regular
+		expression for the pattern.
+		"""
+
+	def __copy__(self: RegexPatternSelf) -> RegexPatternSelf:
+		"""
+		Performa a shallow copy of the pattern.
+
+		Returns the copy (:class:`RegexPattern`).
+		"""
+		other = self.__class__(self.regex, self.include)
+		other.pattern = self.pattern
+		return other
+
+	def __eq__(self, other: RegexPattern) -> bool:
+		"""
+		Tests the equality of this regex pattern with *other* (:class:`RegexPattern`)
+		by comparing their :attr:`~Pattern.include` and :attr:`~RegexPattern.regex`
+		attributes.
+		"""
+		if isinstance(other, RegexPattern):
+			return self.include == other.include and self.regex == other.regex
+		else:
+			return NotImplemented
+
+	@override
+	def match_file(self, file: AnyStr) -> Optional[RegexMatchResult]:
+		"""
+		Matches this pattern against the specified file.
+
+		*file* (:class:`str` or :class:`bytes`) is the file path relative to the
+		root directory (e.g., "relative/path/to/file").
+
+		Returns the match result (:class:`.RegexMatchResult`) if *file* matched;
+		otherwise, :data:`None`.
+		"""
+		if self.include is not None:
+			match = self.regex.search(file)
+			if match is not None:
+				return RegexMatchResult(match)
+
+		return None
+
+	@classmethod
+	def pattern_to_regex(
+		cls,
+		pattern: AnyStr,
+	) -> tuple[Optional[AnyStr], Optional[bool]]:
+		"""
+		Convert the pattern into an uncompiled regular expression.
+
+		*pattern* (:class:`str` or :class:`bytes`) is the pattern to convert into a
+		regular expression.
+
+		Returns a :class:`tuple` containing:
+
+			-	*pattern* (:class:`str`, :class:`bytes` or :data:`None`) is the
+				uncompiled regular expression .
+
+			-	*include* (:class:`bool` or :data:`None`) is whether matched files
+				should be included (:data:`True`), excluded (:data:`False`), or is a
+				null-operation (:data:`None`).
+
+			.. note:: The default implementation simply returns *pattern* and
+			   :data:`True`.
+		"""
+		return pattern, True
+
+
+@dataclass()
+class RegexMatchResult(object):
+	"""
+	The :class:`RegexMatchResult` data class is used to return information about
+	the matched regular expression.
+	"""
+
+	# Keep the class dict-less.
+	__slots__ = (
+		'match',
+	)
+
+	match: re.Match
+	"""
+	*match* (:class:`re.Match`) is the regex match result.
+	"""