Package: pathspec
PathSpecpathspecis a utility library for pattern matching of file paths. So
far this only includes Git’s wildmatch pattern matching which itself is
derived from Rsync’s wildmatch. Git uses wildmatch for itsgitignorefiles.TutorialSay you have a “Projects” directory and you want to back it up, but only
certain files, and ignore others depending on certain conditions:>>> import pathspec
>>> # The gitignore-style patterns for files to select, but we're including
>>> # instead of ignoring.
>>> spec_text = """
...
... # This is a comment because the line begins with a hash: "#"
...
... # Include several project directories (and all descendants) relative to
... # the current directory. To reference a directory you must end with a
... # slash: "/"
... /project-a/
... /project-b/
... /project-c/
...
... # Patterns can be negated by prefixing with exclamation mark: "!"
...
... # Ignore temporary files beginning or ending with "~" and ending with
... # ".swp".
... !~*
... !*~
... !*.swp
...
... # These are python projects so ignore compiled python files from
... # testing.
... !*.pyc
...
... # Ignore the build directories but only directly under the project
... # directories.
... !/*/build/
...
... """We want to use theGitWildMatchPatternclass to compile our patterns. ThePathSpecclass provides an interface around pattern implementations:>>> spec = pathspec.PathSpec.from_lines(pathspec.patterns.GitWildMatchPattern, spec_text.splitlines())That may be a mouthful but it allows for additional patterns to be implemented
in the future without them having to deal with anything but matching the paths
sent to them.GitWildMatchPatternis the implementation of the actual
pattern which internally gets converted into a regular expression.PathSpecis a simple wrapper around a list of compiled patterns.To make things simpler, we can use the registered name for a pattern class
instead of always having to provide a reference to the class itself. TheGitWildMatchPatternclass is registered asgitwildmatch:>>> spec = pathspec.PathSpec.from_lines('gitwildmatch', spec_text.splitlines())If we wanted to manually compile the patterns we can just do the following:>>> patterns = map(pathspec.patterns.GitWildMatchPattern, spec_text.splitlines())
>>> spec = PathSpec(patterns)PathSpec.from_lines()is simply a class method which does just that.If you want to load the patterns from file, you can pass the file instance
directly as well:>>> with open('patterns.list', 'r') as fh:
>>>     spec = pathspec.PathSpec.from_lines('gitwildmatch', fh)You can perform matching on a whole directory tree with:>>> matches = spec.match_tree('path/to/directory')Or you can perform matching on a specific set of file paths with:>>> matches = spec.match_files(file_paths)Or check to see if an individual file matches:>>> is_matched = spec.match_file(file_path)There is a specialized class,pathspec.GitIgnoreSpec, which more closely
implements the behavior ofgitignore. This usesGitWildMatchPatternpattern by default and handles some edge cases differently from the genericPathSpecclass.GitIgnoreSpeccan be used without specifying the pattern
factory:>>> spec = pathspec.GitIgnoreSpec.from_lines(spec_text.splitlines())Licensepathspecis licensed under theMozilla Public License Version 2.0. SeeLICENSEor theFAQfor more information.In summary, you may usepathspecwith any closed or open source project
without affecting the license of the larger work so long as you:give credit where credit is due,and release any custom changes made topathspec.SourceThe source code forpathspecis available from the GitHub repocpburnz/python-pathspec.Installationpathspecis available for install throughPyPI:pip install pathspecpathspeccan also be built from source. The following packages will be
required:build(>=0.6.0)pathspeccan then be built and installed with:python -m build
pip install dist/pathspec-*-py3-none-any.whlDocumentationDocumentation forpathspecis available onRead the Docs.Other LanguagesThe related projectpathspec-ruby(byhighb) provides a similar library as
aRuby gem.Change History0.12.1 (2023-12-10)Bug fixes:Issue #84: PathSpec.match_file() returns None since 0.12.0.0.12.0 (2023-12-09)Major changes:Dropped support of EOL Python 3.7. SeePull #82.API changes:Signature of protected methodpathspec.pathspec.PathSpec._match_file()(with a leading underscore) has been changed fromdef _match_file(patterns: Iterable[Pattern], file: str) -> booltodef _match_file(patterns: Iterable[Tuple[int, Pattern]], file: str) -> Tuple[Optional[bool], Optional[int]].New features:Addedpathspec.pathspec.PathSpec.check_*()methods. These methods behave similarly to.match_*()but return additional information in thepathspec.util.CheckResultobjects (e.g.,CheckResult.indexindicates the index of the last pattern that matched the file).Addedpathspec.pattern.RegexPattern.patternattribute which stores the original, uncompiled pattern.Bug fixes:Issue #81: GitIgnoreSpec behaviors differ from git.Pull #83: Fix ReadTheDocs builds.Improvements:Mark Python 3.12 as supported. SeePull #82.Improve test debugging.Improve type hint onon_errorparameter onpathspec.pathspec.PathSpec.match_tree_entries().Improve type hint onon_errorparameter onpathspec.util.iter_tree_entries().0.11.2 (2023-07-28)New features:Issue #80: match_files with negated path spec.pathspec.PathSpec.match_*()now have anegateparameter to make using.gitignorelogic easier and more efficient.Bug fixes:Pull #76: Add edge case: patterns that end with an escaped spaceIssue #77/Pull #78: Negate with caret symbol as with the exclamation mark.0.11.1 (2023-03-14)Bug fixes:Issue #74: Include directory should override exclude file.Improvements:Pull #75: Fix partially unknown PathLike type.Convertos.PathLiketo a string properly usingos.fspath.0.11.0 (2023-01-24)Major changes:Changed build backend toflit_core.buildapifromsetuptools.build_meta. Building withsetuptoolsthroughsetup.pyis still supported for distributions that need it. SeeIssue #72.Improvements:Issue #72/Pull #73: Please consider switching the build-system to flit_core to ease setuptools bootstrap.0.10.3 (2022-12-09)New features:Added utility functionpathspec.util.append_dir_sep()to aid in distinguishing between directories and files on the file-system. SeeIssue #65.Bug fixes:Issue #66/Pull #67: Package not marked as py.typed.Issue #68: Exports are considered private.Issue #70/Pull #71: ‘Self’ string literal type is Unknown in pyright.Improvements:Issue #65: Checking directories via match_file() does not work on Path objects.0.10.2 (2022-11-12)Bug fixes:Fix failing tests on Windows.Type hint onrootparameter onpathspec.pathspec.PathSpec.match_tree_entries().Type hint onrootparameter onpathspec.pathspec.PathSpec.match_tree_files().Type hint onrootparameter onpathspec.util.iter_tree_entries().Type hint onrootparameter onpathspec.util.iter_tree_files().Issue #64: IndexError with my .gitignore file when trying to build a Python package.Improvements:Pull #58: CI: add GitHub Actions test workflow.0.10.1 (2022-09-02)Bug fixes:Fix documentation onpathspec.pattern.RegexPattern.match_file().Pull #60: Remove redundant wheel dep from pyproject.toml.Issue #61: Dist failure for Fedora, CentOS, EPEL.Issue #62: Since version 0.10.0 pure wildcard does not work in some cases.Improvements:Restore support for legacy installations usingsetup.py. SeeIssue #61.0.10.0 (2022-08-30)Major changes:Dropped support of EOL Python 2.7, 3.5, 3.6. SeeIssue #47.Thegitwildmatchpatterndir/*is now handled the same asdir/. This meansdir/*will now match all descendants rather than only direct children. SeeIssue #19.Addedpathspec.GitIgnoreSpecclass (see new features).Changed build system topyproject.tomland build backend tosetuptools.build_metawhich may have unforeseen consequences.Renamed GitHub project frompython-path-specificationtopython-pathspec. SeeIssue #35.API changes:Deprecated:pathspec.util.match_files()is an old function no longer used.Deprecated:pathspec.match_files()is an old function no longer used.Deprecated:pathspec.util.normalize_files()is no longer used.Deprecated:pathspec.util.iter_tree()is an alias forpathspec.util.iter_tree_files().Deprecated:pathspec.iter_tree()is an alias forpathspec.util.iter_tree_files().Deprecated:pathspec.pattern.Pattern.match()is no longer used. Use or implementpathspec.pattern.Pattern.match_file().New features:Added classpathspec.gitignore.GitIgnoreSpec(with aliaspathspec.GitIgnoreSpec) to implementgitignorebehavior not possible with standardPathSpecclass. The particulargitignorebehavior implemented is prioritizing patterns matching the file directly over matching an ancestor directory.Bug fixes:Issue #19: Files inside an ignored sub-directory are not matched.Issue #41: Incorrectly (?) matches files inside directories that do match.Pull #51: Refactor deprecated unittest aliases for Python 3.11 compatibility.Issue #53: Symlink pathspec_meta.py breaks Windows.Issue #54: test_util.py uses os.symlink which can fail on Windows.Issue #55: Backslashes at start of pattern not handled correctly.Pull #56: pyproject.toml: include subpackages in setuptools configIssue #57:!doesn’t exclude files in directories if the pattern doesn’t have a trailing slash.Improvements:Support Python 3.10, 3.11.Modernize code to Python 3.7.Issue #52: match_files() is not a pure generator function, and it impacts tree_*() gravely.0.9.0 (2021-07-17)Issue #44/Pull #50: RaiseGitWildMatchPatternErrorfor invalid git patterns.Pull #45: Fix for duplicate leading double-asterisk, and edge cases.Issue #46: Fix matching absolute paths.API change:util.normalize_files()now returns aDict[str, List[pathlike]]instead of aDict[str, pathlike].Added type hinting.0.8.1 (2020-11-07)Pull #43: Add support for addition operator.0.8.0 (2020-04-09)Issue #30: Expose what patterns matched paths. Addedutil.detailed_match_files().Issue #31:match_tree()doesn’t return symlinks.Issue #34: Supportpathlib.Paths.AddPathSpec.match_tree_entriesandutil.iter_tree_entries()to support directories and symlinks.API change:match_tree()has been renamed tomatch_tree_files(). The old namematch_tree()is still available as an alias.API change:match_tree_files()now returns symlinks. This is a bug fix but it will change the returned results.0.7.0 (2019-12-27)Pull #28: Add support for Python 3.8, and drop Python 3.4.Pull #29: Publish bdist wheel.0.6.0 (2019-10-03)Pull #24: Drop support for Python 2.6, 3.2, and 3.3.Pull #25: Update README.rst.Pull #26: Method to escape gitwildmatch.0.5.9 (2018-09-15)Fixed file system error handling.0.5.8 (2018-09-15)Improved type checking.Created scripts to test Python 2.6 because Tox removed support for it.Improved byte string handling in Python 3.Issue #22: Handle dangling symlinks.0.5.7 (2018-08-14)Issue #21: Fix collections deprecation warning.0.5.6 (2018-04-06)Improved unit tests.Improved type checking.Issue #20: Support current directory prefix.0.5.5 (2017-09-09)Add documentation link to README.0.5.4 (2017-09-09)Pull #17: Add link to Ruby implementation ofpathspec.Add sphinx documentation.0.5.3 (2017-07-01)Issue #14: Fix byte strings for Python 3.Pull #15: Include “LICENSE” in source package.Issue #16: Support Python 2.6.0.5.2 (2017-04-04)Fixed change log.0.5.1 (2017-04-04)Pull #13: Add equality methods toPathSpecandRegexPattern.0.5.0 (2016-08-22)Issue #12: AddPathSpec.match_file().Renamedgitignore.GitIgnorePatterntopatterns.gitwildmatch.GitWildMatchPattern.Deprecatedgitignore.GitIgnorePattern.0.4.0 (2016-07-15)Issue #11: Support converting patterns into regular expressions without compiling them.API change: Subclasses ofRegexPatternshould implementpattern_to_regex().0.3.4 (2015-08-24)Pull #7: Fixed non-recursive links.Pull #8: Fixed edge cases in gitignore patterns.Pull #9: Fixed minor usage documentation.Fixed recursion detection.Fixed trivial incompatibility with Python 3.2.0.3.3 (2014-11-21)Improved documentation.0.3.2 (2014-11-08)Pull #5: Use tox for testing.Issue #6: Fixed matching Windows paths.Improved documentation.API change:spec.match_tree()andspec.match_files()now return iterators instead of sets.0.3.1 (2014-09-17)Updated README.0.3.0 (2014-09-17)Pull #3: Fixed trailing slash in gitignore patterns.Pull #4: Fixed test for trailing slash in gitignore patterns.Added registered patterns.0.2.2 (2013-12-17)Fixed setup.py.0.2.1 (2013-12-17)Added tests.Fixed comment gitignore patterns.Fixed relative path gitignore patterns.0.2.0 (2013-12-07)Initial release.