Improve debugging

CHANGES.rst

@@ -2,13 +2,29 @@
 Change History
 ==============
 
-0.11.3 (TDB)
+0.12.0 (TDB)
 ------------
 
+API changes:
+
+- Signature of protected method `pathspec.pathspec.PathSpec._match_file()` has been changed from `def _match_file(patterns: Iterable[Pattern], file: str) -> bool` to `def _match_file(patterns: Iterable[Tuple[int, Pattern]], file: str) -> Tuple[Optional[bool], Optional[int]]`.
+
+New features:
+
+- Added `pathspec.pathspec.PathSpec.check_*()` methods. These methods behave similarly to `.match_*()` but return additional information in the `pathspec.util.CheckResult` objects (e.g., `CheckResult.index` indicates the index of the last pattern that matched the file).
+- Added `pathspec.pattern.RegexPattern.pattern` attribute which stores the original, uncompiled pattern.
+
+
 Bug fixes:
 
 - `Pull #83`_: Fix ReadTheDocs builds.
 
+Improvements:
+
+- Improve test debugging.
+- Improve type hint on *on_error* parameter on `pathspec.pathspec.PathSpec.match_tree_entries()`.
+- Improve type hint on *on_error* parameter on `pathspec.util.iter_tree_entries()`.
+
 
 .. _`Pull #83`: https://github.com/cpburnz/python-pathspec/pull/83
 

DEV.md

@@ -96,7 +96,7 @@ Review the following Linux distributions.
 	- [Releases](https://wiki.ubuntu.com/Releases)
 	- Package: [python3](https://packages.ubuntu.com/focal/python3) (focal)
 	- Package: [python3](https://packages.ubuntu.com/jammy/python3) (jammy)
-	- Package: [python3-pathspec](https://packages.ubuntu.com/focal/python3-pathspec) (flocal)
+	- Package: [python3-pathspec](https://packages.ubuntu.com/focal/python3-pathspec) (focal)
 	- Package: [python3-pathspec](https://packages.ubuntu.com/jammy/python3-pathspec) (jammy)
 
 

pathspec/_meta.py

@@ -55,4 +55,4 @@
 	"kurtmckee <https://github.com/kurtmckee>",
 ]
 __license__ = "MPL 2.0"
-__version__ = "0.11.3.dev1"
+__version__ = "0.12.0.dev1"

pathspec/gitignore.py

@@ -5,12 +5,15 @@
 
 from typing import (
 	AnyStr,
-	Callable,
-	Collection,
-	Iterable,
-	Type,
+	Callable,  # Replaced by `collections.abc.Callable` in 3.9.
+	Iterable,  # Replaced by `collections.abc.Iterable` in 3.9.
+	Optional,  # Replaced by `X | None` in 3.10.
+	Tuple,  # Replaced by `tuple` in 3.9.
+	Type,  # Replaced by `type` in 3.9.
 	TypeVar,
-	Union)
+	Union,  # Replaced by `X | Y` in 3.10.
+	cast,
+	overload)
 
 from .pathspec import (
 	PathSpec)
@@ -48,6 +51,25 @@ def __eq__(self, other: object) -> bool:
 		else:
 			return NotImplemented
 
+	# Support reversed order of arguments from PathSpec.
+	@overload
+	@classmethod
+	def from_lines(
+		cls: Type[Self],
+		pattern_factory: Union[str, Callable[[AnyStr], Pattern]],
+		lines: Iterable[AnyStr],
+	) -> Self:
+		...
+
+	@overload
+	@classmethod
+	def from_lines(
+		cls: Type[Self],
+		lines: Iterable[AnyStr],
+		pattern_factory: Union[str, Callable[[AnyStr], Pattern], None] = None,
+	) -> Self:
+		...
+
 	@classmethod
 	def from_lines(
 		cls: Type[Self],
@@ -74,36 +96,40 @@ def from_lines(
 		if pattern_factory is None:
 			pattern_factory = GitWildMatchPattern
 
-		elif (isinstance(lines, str) or callable(lines)) and _is_iterable(pattern_factory):
+		elif (isinstance(lines, (str, bytes)) or callable(lines)) and _is_iterable(pattern_factory):
 			# Support reversed order of arguments from PathSpec.
 			pattern_factory, lines = lines, pattern_factory
 
 		self = super().from_lines(pattern_factory, lines)
-		return self  # type: ignore
+		return cast(Self, self)
 
 	@staticmethod
 	def _match_file(
-		patterns: Collection[GitWildMatchPattern],
+		patterns: Iterable[Tuple[int, GitWildMatchPattern]],
 		file: str,
-	) -> bool:
+	) -> Tuple[Optional[bool], Optional[int]]:
 		"""
-		Matches the file to the patterns.
+		Check the file against the patterns.
 
-		.. NOTE:: Subclasses of :class:`.PathSpec` may override this
-		   method as an instance method. It does not have to be a static
-		   method.
+		.. NOTE:: Subclasses of :class:`~pathspec.pathspec.PathSpec` may override
+		   this method as an instance method. It does not have to be a static
+		   method. The signature for this method is subject to change.
 
-		*patterns* (:class:`~collections.abc.Iterable` of :class:`~pathspec.pattern.Pattern`)
-		contains the patterns to use.
+		*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*.
+		*file* (:class:`str`) is the normalized file path to be matched against
+		*patterns*.
 
-		Returns :data:`True` if *file* matched; otherwise, :data:`False`.
+		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_matched = False
+		out_include: Optional[bool] = None
+		out_index: Optional[int] = None
 		out_priority = 0
-		for pattern in patterns:
+		for index, pattern in patterns:
 			if pattern.include is not None:
 				match = pattern.match_file(file)
 				if match is not None:
@@ -112,6 +138,9 @@ def _match_file(
 					# Check for directory marker.
 					dir_mark = match.match.groupdict().get(_DIR_MARK)
 
+					# TODO: A exclude (whitelist) dir pattern here needs to deprioritize
+					# for 81-c.
+
 					if dir_mark:
 						# Pattern matched by a directory pattern.
 						priority = 1
@@ -120,10 +149,10 @@ def _match_file(
 						priority = 2
 
 					if pattern.include and dir_mark:
-						out_matched = pattern.include
+						out_include = pattern.include
 						out_priority = priority
 					elif priority >= out_priority:
-						out_matched = pattern.include
+						out_include = pattern.include
 						out_priority = priority
 
-		return out_matched
+		return out_include, out_index