Detailed tree work

pathspec/__init__.py

@@ -51,8 +51,8 @@
 __license__ = "MPL 2.0"
 __project__ = "pathspec"
 __status__ = "Development"
-__updated__ = "2019-12-27"
-__version__ = "0.7.0"
+__updated__ = "2020-01-21"
+__version__ = "0.8.0.dev1"
 
 from .pathspec import PathSpec
 from .pattern import Pattern, RegexPattern

pathspec/pathspec.py

@@ -125,7 +125,6 @@ def match_tree(self, root, on_error=None, follow_links=None):
 		optionally is the error handler for file-system exceptions. See
 		:func:`~pathspec.util.iter_tree` for more information.
 
-
 		*follow_links* (:class:`bool` or :data:`None`) optionally is whether
 		to walk symbolik links that resolve to directories. See
 		:func:`~pathspec.util.iter_tree` for more information.

pathspec/util.py

@@ -24,6 +24,41 @@
 registered pattern factory (``callable``).
 """
 
+def detailed_match_files(patterns, files):
+	"""
+	Matches the files to the patterns, and returns which patterns matched
+	the files.
+
+	*patterns* (:class:`~collections.abc.Iterable` of :class:`~pathspec.pattern.Pattern`)
+	contains the patterns to use.
+
+	*files* (:class:`~collections.abc.Iterable` of :class:`str`) contains
+	the normalized file paths to be matched against *patterns*.
+
+	Returns the matched files (:class:`dict`) which maps each mapped file
+	(:class:`str`) to the patterns that matched in order (:class:`list` of
+	:class:`~pathspec.pattern.Pattern`).
+	"""
+	all_files = files if isinstance(files, collection_type) else list(files)
+	return_files = {}
+	for pattern in patterns:
+		if pattern.include is not None:
+			result_files = pattern.match(all_files)
+			if pattern.include:
+				# Add files and record pattern.
+				for result_file in result_files:
+					if result_file in return_files:
+						return_files[result_file].append(pattern)
+					else:
+						return_files[result_file] = [pattern]
+
+			else:
+				# Remove files.
+				for file in result_files:
+					del return_files[file]
+
+	return return_files
+
 def iter_tree(root, on_error=None, follow_links=None):
 	"""
 	Walks the specified directory for all files.
@@ -54,6 +89,36 @@ def iter_tree(root, on_error=None, follow_links=None):
 	for file_rel in _iter_tree_next(os.path.abspath(root), '', {}, on_error, follow_links):
 		yield file_rel
 
+def iter_tree_entries(root, on_error=None, follow_links=None):
+	"""
+	Walks the specified directory for all files.
+
+	*root* (:class:`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. It will be
+	called with the exception (:exc:`OSError`). Reraise the exception to
+	abort the walk. Default is :data:`None` to ignore file-system
+	exceptions.
+
+	*follow_links* (:class:`bool` or :data:`None`) optionally is whether
+	to walk symbolic links that resolve to directories. Default is
+	:data:`None` for :data:`True`.
+
+	Raises :exc:`RecursionError` if recursion is detected.
+
+	Returns an :class:`~collections.abc.Iterable` yielding each file or
+	directory entry (:class:`.TreeEntry`) relative to *root*.
+	"""
+	if on_error is not None and not callable(on_error):
+		raise TypeError("on_error:{!r} is not callable.".format(on_error))
+
+	if follow_links is None:
+		follow_links = True
+
+	for file_rel in _iter_tree_entries_next(os.path.abspath(root), '', {}, on_error, follow_links):
+		yield file_rel
+
 def _iter_tree_next(root_full, dir_rel, memo, on_error, follow_links):
 	"""
 	Scan the directory for all descendant files.
@@ -125,6 +190,84 @@ def _iter_tree_next(root_full, dir_rel, memo, on_error, follow_links):
 	# a recursion. See <https://github.com/cpburnz/python-path-specification/pull/7>.
 	del memo[dir_real]
 
+
+def _iter_tree_entries_next(root_full, dir_rel, memo, on_error, follow_links):
+	"""
+	Scan the directory for all descendant files.
+
+	*root_full* (:class:`str`) the absolute path to the root directory.
+
+	*dir_rel* (:class:`str`) the path to the directory to scan relative to
+	*root_full*.
+
+	*memo* (:class:`dict`) keeps track of ancestor directories
+	encountered. Maps each ancestor real path (:class:`str``) to relative
+	path (:class:`str`).
+
+	*on_error* (:class:`~collections.abc.Callable` or :data:`None`)
+	optionally is the error handler for file-system exceptions.
+
+	*follow_links* (:class:`bool`) is whether to walk symbolik links that
+	resolve to directories.
+
+	Yields each entry (:class:`.TreeEntry`).
+	"""
+	dir_full = os.path.join(root_full, dir_rel)
+	dir_real = os.path.realpath(dir_full)
+
+	# Remember each encountered ancestor directory and its canonical
+	# (real) path. If a canonical path is encountered more than once,
+	# recursion has occurred.
+	if dir_real not in memo:
+		memo[dir_real] = dir_rel
+	else:
+		raise RecursionError(real_path=dir_real, first_path=memo[dir_real], second_path=dir_rel)
+
+	for node_name in os.listdir(dir_full):
+		node_rel = os.path.join(dir_rel, node_name)
+		node_full = os.path.join(root_full, node_rel)
+
+		# Inspect child node.
+		try:
+			node_lstat = os.lstat(node_full)
+		except OSError as e:
+			if on_error is not None:
+				on_error(e)
+			continue
+
+		if stat.S_ISLNK(node_lstat.st_mode):
+			# Child node is a link, inspect the target node.
+			is_link = True
+			try:
+				node_stat = os.stat(node_full)
+			except OSError as e:
+				if on_error is not None:
+					on_error(e)
+				continue
+		else:
+			is_link = False
+			node_stat = node_lstat
+
+		if stat.S_ISDIR(node_stat.st_mode) and (follow_links or not is_link):
+			# Child node is a directory, recurse into it and yield its
+			# decendant files.
+			yield TreeEntry(node_name, node_rel, node_lstat, node_stat)
+
+			for entry in _iter_tree_entries_next(root_full, node_rel, memo, on_error, follow_links):
+				yield entry
+
+		elif stat.S_ISREG(node_stat.st_mode):
+			# Child node is a file, yield it.
+			yield TreeEntry(node_name, node_rel, node_lstat, node_stat)
+
+	# NOTE: Make sure to remove the canonical (real) path of the directory
+	# from the ancestors memo once we are done with it. This allows the
+	# same directory to appear multiple times. If this is not done, the
+	# second occurance of the directory will be incorrectly interpreted as
+	# a recursion. See <https://github.com/cpburnz/python-path-specification/pull/7>.
+	del memo[dir_real]
+
+
 def lookup_pattern(name):
 	"""
 	Lookups a registered pattern factory by name.
@@ -348,3 +491,106 @@ def second_path(self):
 		:attr:`self.real_path <RecursionError.real_path>`.
 		"""
 		return self.args[2]
+
+
+class TreeEntry(object):
+	"""
+	The :class:`.TreeEntry` class contains information about a file-system
+	entry.
+	"""
+
+	#: Make the class dict-less.
+	__slots__ = ('_lstat', 'name', 'path', '_stat')
+
+	def __init__(self, name, path, lstat, stat):
+		"""
+		Initialize the :class:`.TreeEntry` instancel.
+
+		*name* (:class:`str`) is the base name of the entry.
+
+		*path* (:class:`str`) is the path of the entry.
+
+		*lstat* (:class:`~os.stat_result`) is the stat result of the direct
+		entry.
+
+		*stat* (:class:`~os.stat_result`) is the stat result of the entry,
+		potentially linked.
+		"""
+
+		self._lstat = lstat
+		"""
+		*_lstat* (:class:`~os.stat_result`) is the stat result of the direct
+		entry.
+		"""
+
+		self.name = name
+		"""
+		*name* (:class:`str`) is the base name of the entry.
+		"""
+
+		self.path = path
+		"""
+		*path* (:class:`str`) is the path of the entry.
+		"""
+
+		self._stat = stat
+		"""
+		*_stat* (:class:`~os.stat_result`) is the stat result of the linked
+		entry.
+		"""
+
+	def is_dir(follow_symlinks=None):
+		"""
+		Get whether the entry is a directory.
+
+		*follow_symlinks* (:class:`bool` or :data:`None`) is whether to
+		follow symbolic links. If this is :data:`True`, a symlink to a
+		directory will result in :data:`True`. Default is :data:`None` for
+		:data:`True`.
+
+		Returns whether the entry is a directory (:class:`bool`).
+		"""
+		if follow_symlinks is None:
+			follow_symlinks = True
+
+		node_stat = self._stat if follow_symlinks else self._lstat
+		return stat.S_ISDIR(node_stat.st_mode)
+
+	def is_file(follow_symlinks=None):
+		"""
+		Get whether the entry is a regular file.
+
+		*follow_symlinks* (:class:`bool` or :data:`None`) is whether to
+		follow symbolic links. If this is :data:`True`, a symlink to a
+		regular file will result in :data:`True`. Default is :data:`None`
+		for :data:`True`.
+
+		Returns whether the entry is a regular file (:class:`bool`).
+		"""
+		if follow_symlinks is None:
+			follow_symlinks = True
+
+		node_stat = self._stat if follow_symlinks else self._lstat
+		return stat.S_ISREG(node_stat.st_mode)
+
+	def is_symlink():
+		"""
+		Returns whether the entry is a symbolic link (:class:`bool`).
+		"""
+		return stat.S_ISLNK(self._lstat.st_mode)
+
+	def stat(follow_symlinks=None):
+		"""
+		Get the cached stat result for the entry.
+
+		*follow_symlinks* (:class:`bool` or :data:`None`) is whether to
+		follow symbolic links. If this is :data:`True`, the stat result of
+		the linked file will be returned. Default is :data:`None` for
+		:data:`True`.
+
+		Returns that stat result (:class:`~os.stat_result`).
+		"""
+		if follow_symlinks is None:
+			follow_links = True
+
+		return self._stat if follow_symlinks else self._lstat