Add type hints

CHANGES.rst

@@ -8,6 +8,7 @@ Change History
 - `Issue #45`_: Fix for duplicate leading double-asterisk, and edge cases.
 - `Issue #46`_: Fix matching absolute paths.
 - API change: `util.normalize_files()` now returns a `Dict[str, List[pathlike]]` instead of a `Dict[str, pathlike]`.
+- Added type hinting.
 
 .. _`Issue #45`: https://github.com/cpburnz/python-path-specification/pull/45
 .. _`Issue #46`: https://github.com/cpburnz/python-path-specification/issues/46

pathspec/compat.py

@@ -36,3 +36,6 @@ def iterkeys(mapping):
 except ImportError:
 	# Python 2.7 - 3.5.
 	from collections import Container as Collection
+
+CollectionType = Collection
+IterableType = Iterable

pathspec/pathspec.py

@@ -4,8 +4,34 @@
 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 Collection, iterkeys, izip_longest, string_types, unicode
+from .compat import (
+	CollectionType,
+	iterkeys,
+	izip_longest,
+	string_types)
+from .pattern import Pattern
+from .util import TreeEntry
 
 
 class PathSpec(object):
@@ -15,20 +41,22 @@ class PathSpec(object):
 	"""
 
 	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, Collection) else list(patterns)
+		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.
@@ -47,6 +75,7 @@ def __len__(self):
 		return len(self.patterns)
 
 	def __add__(self, other):
+		# type: (PathSpec) -> PathSpec
 		"""
 		Combines the :attr:`Pathspec.patterns` patterns from two
 		:class:`PathSpec` instances.
@@ -57,6 +86,7 @@ def __add__(self, other):
 			return NotImplemented
 
 	def __iadd__(self, other):
+		# type: (PathSpec) -> PathSpec
 		"""
 		Adds the :attr:`Pathspec.patterns` patterns from one :class:`PathSpec`
 		instance to this instance.
@@ -69,6 +99,7 @@ def __iadd__(self, other):
 
 	@classmethod
 	def from_lines(cls, pattern_factory, lines):
+		# type: (Union[Text, Callable[[AnyStr], Pattern]], Iterable[AnyStr]) -> PathSpec
 		"""
 		Compiles the pattern lines.
 
@@ -92,10 +123,11 @@ def from_lines(cls, pattern_factory, lines):
 		if not util._is_iterable(lines):
 			raise TypeError("lines:{!r} is not an iterable.".format(lines))
 
-		lines = [pattern_factory(line) for line in lines if line]
-		return cls(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.
 
@@ -112,6 +144,7 @@ def match_file(self, file, separators=None):
 		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.
 
@@ -123,7 +156,7 @@ def match_entries(self, entries, separators=None):
 		normalize. See :func:`~pathspec.util.normalize_file` for more
 		information.
 
-		Returns the matched entries (:class:`~collections.abc.Iterable` of
+		Returns the matched entries (:class:`~collections.abc.Iterator` of
 		:class:`~util.TreeEntry`).
 		"""
 		if not util._is_iterable(entries):
@@ -135,6 +168,7 @@ def match_entries(self, entries, separators=None):
 			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.
 
@@ -147,8 +181,8 @@ def match_files(self, files, separators=None):
 		normalize. See :func:`~pathspec.util.normalize_file` for more
 		information.
 
-		Returns the matched files (:class:`~collections.abc.Iterable` of
-		:class:`str`).
+		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))
@@ -160,6 +194,7 @@ def match_files(self, files, separators=None):
 				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.
@@ -175,13 +210,14 @@ def match_tree_entries(self, root, on_error=None, follow_links=None):
 		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`).
+		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.

pathspec/pattern.py

@@ -4,6 +4,18 @@
 """
 
 import re
+try:
+	from typing import (
+		AnyStr,
+		Iterable,
+		Iterator,
+		Optional,
+		Pattern as RegexHint,
+		Text,
+		Tuple,
+		Union)
+except ImportError:
+	pass
 
 from .compat import unicode
 
@@ -17,6 +29,7 @@ class Pattern(object):
 	__slots__ = ('include',)
 
 	def __init__(self, include):
+		# type: (Optional[bool]) -> None
 		"""
 		Initializes the :class:`Pattern` instance.
 
@@ -33,6 +46,7 @@ def __init__(self, include):
 		"""
 
 	def match(self, files):
+		# type: (Iterable[Text]) -> Iterator[Text]
 		"""
 		Matches this pattern against the specified files.
 
@@ -55,6 +69,7 @@ class RegexPattern(Pattern):
 	__slots__ = ('regex',)
 
 	def __init__(self, pattern, include=None):
+		# type: (Union[AnyStr, RegexHint], Optional[bool]) -> None
 		"""
 		Initializes the :class:`RegexPattern` instance.
 
@@ -103,6 +118,7 @@ def __init__(self, pattern, include=None):
 		self.regex = regex
 
 	def __eq__(self, other):
+		# type: (RegexPattern) -> bool
 		"""
 		Tests the equality of this regex pattern with *other* (:class:`RegexPattern`)
 		by comparing their :attr:`~Pattern.include` and :attr:`~RegexPattern.regex`
@@ -114,6 +130,7 @@ def __eq__(self, other):
 			return NotImplemented
 
 	def match(self, files):
+		# type: (Iterable[Text]) -> Iterable[Text]
 		"""
 		Matches this pattern against the specified files.
 
@@ -130,6 +147,7 @@ def match(self, files):
 
 	@classmethod
 	def pattern_to_regex(cls, pattern):
+		# type: (Text) -> Tuple[Text, bool]
 		"""
 		Convert the pattern into an uncompiled regular expression.
 

pathspec/patterns/gitwildmatch.py

@@ -8,6 +8,14 @@
 
 import re
 import warnings
+try:
+	from typing import (
+		AnyStr,
+		Optional,
+		Text,
+		Tuple)
+except ImportError:
+	pass
 
 from .. import util
 from ..compat import unicode
@@ -28,6 +36,7 @@ class GitWildMatchPattern(RegexPattern):
 
 	@classmethod
 	def pattern_to_regex(cls, pattern):
+		# type: (AnyStr) -> Tuple[Optional[AnyStr], Optional[bool]]
 		"""
 		Convert the pattern into a regular expression.
 
@@ -205,6 +214,7 @@ def pattern_to_regex(cls, pattern):
 
 	@staticmethod
 	def _translate_segment_glob(pattern):
+		# type: (Text) -> Text
 		"""
 		Translates the glob pattern to a regular expression. This is used in
 		the constructor to translate a path segment glob pattern to its
@@ -245,28 +255,28 @@ def _translate_segment_glob(pattern):
 				regex += '[^/]'
 
 			elif char == '[':
-				# Braket expression wildcard. Except for the beginning
-				# exclamation mark, the whole braket expression can be used
+				# Bracket expression wildcard. Except for the beginning
+				# exclamation mark, the whole bracket expression can be used
 				# directly as regex but we have to find where the expression
 				# ends.
-				# - "[][!]" matchs ']', '[' and '!'.
-				# - "[]-]" matchs ']' and '-'.
-				# - "[!]a-]" matchs any character except ']', 'a' and '-'.
+				# - "[][!]" matches ']', '[' and '!'.
+				# - "[]-]" matches ']' and '-'.
+				# - "[!]a-]" matches any character except ']', 'a' and '-'.
 				j = i
 				# Pass brack expression negation.
 				if j < end and pattern[j] == '!':
 					j += 1
-				# Pass first closing braket if it is at the beginning of the
+				# Pass first closing bracket if it is at the beginning of the
 				# expression.
 				if j < end and pattern[j] == ']':
 					j += 1
-				# Find closing braket. Stop once we reach the end or find it.
+				# Find closing bracket. Stop once we reach the end or find it.
 				while j < end and pattern[j] != ']':
 					j += 1
 
 				if j < end:
-					# Found end of braket expression. Increment j to be one past
-					# the closing braket:
+					# Found end of bracket expression. Increment j to be one past
+					# the closing bracket:
 					#
 					#  [...]
 					#   ^   ^
@@ -280,27 +290,27 @@ def _translate_segment_glob(pattern):
 						expr += '^'
 						i += 1
 					elif pattern[i] == '^':
-						# POSIX declares that the regex braket expression negation
+						# POSIX declares that the regex bracket expression negation
 						# "[^...]" is undefined in a glob pattern. Python's
 						# `fnmatch.translate()` escapes the caret ('^') as a
 						# literal. To maintain consistency with undefined behavior,
 						# I am escaping the '^' as well.
 						expr += '\\^'
 						i += 1
 
-					# Build regex braket expression. Escape slashes so they are
+					# Build regex bracket expression. Escape slashes so they are
 					# treated as literal slashes by regex as defined by POSIX.
 					expr += pattern[i:j].replace('\\', '\\\\')
 
-					# Add regex braket expression to regex result.
+					# Add regex bracket expression to regex result.
 					regex += expr
 
-					# Set i to one past the closing braket.
+					# Set i to one past the closing bracket.
 					i = j
 
 				else:
-					# Failed to find closing braket, treat opening braket as a
-					# braket literal instead of as an expression.
+					# Failed to find closing bracket, treat opening bracket as a
+					# bracket literal instead of as an expression.
 					regex += '\\['
 
 			else:
@@ -311,18 +321,33 @@ def _translate_segment_glob(pattern):
 
 	@staticmethod
 	def escape(s):
+		# type: (AnyStr) -> AnyStr
 		"""
 		Escape special characters in the given string.
 
 		*s* (:class:`unicode` or :class:`bytes`) a filename or a string
 		that you want to escape, usually before adding it to a `.gitignore`
 
-		Returns the escaped string (:class:`unicode`, :class:`bytes`)
+		Returns the escaped string (:class:`unicode` or :class:`bytes`)
 		"""
+		if isinstance(s, unicode):
+			return_type = unicode
+			string = s
+		elif isinstance(s, bytes):
+			return_type = bytes
+			string = s.decode(_BYTES_ENCODING)
+		else:
+			raise TypeError("s:{!r} is not a unicode or byte string.".format(s))
+
 		# Reference: https://git-scm.com/docs/gitignore#_pattern_format
 		meta_characters = r"[]!*#?"
 
-		return "".join("\\" + x if x in meta_characters else x for x in s)
+		out_string = "".join("\\" + x if x in meta_characters else x for x in string)
+
+		if return_type is bytes:
+			return out_string.encode(_BYTES_ENCODING)
+		else:
+			return out_string
 
 util.register_pattern('gitwildmatch', GitWildMatchPattern)
 
@@ -338,7 +363,7 @@ def __init__(self, *args, **kw):
 		Warn about deprecation.
 		"""
 		self._deprecated()
-		return super(GitIgnorePattern, self).__init__(*args, **kw)
+		super(GitIgnorePattern, self).__init__(*args, **kw)
 
 	@staticmethod
 	def _deprecated():