| Name | pathspec JSON |
| Version |
0.12.1
JSON |
| download |
| home_page | |
| Summary | Utility library for gitignore style pattern matching of file paths. |
| upload_time | 2023-12-10 22:30:45 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.8 |
| license | |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
PathSpec
========
*pathspec* is 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 its `gitignore`_
files.
.. _`gitignore`: http://git-scm.com/docs/gitignore
Tutorial
--------
Say 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 the ``GitWildMatchPattern`` class to compile our patterns. The
``PathSpec`` class 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. ``GitWildMatchPattern`` is the implementation of the actual
pattern which internally gets converted into a regular expression. ``PathSpec``
is 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. The
``GitWildMatchPattern`` class is registered as **gitwildmatch**::
>>> 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 of **gitignore**. This uses ``GitWildMatchPattern``
pattern by default and handles some edge cases differently from the generic
``PathSpec`` class. ``GitIgnoreSpec`` can be used without specifying the pattern
factory::
>>> spec = pathspec.GitIgnoreSpec.from_lines(spec_text.splitlines())
License
-------
*pathspec* is licensed under the `Mozilla Public License Version 2.0`_. See
`LICENSE`_ or the `FAQ`_ for more information.
In summary, you may use *pathspec* with 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 to *pathspec*.
.. _`Mozilla Public License Version 2.0`: http://www.mozilla.org/MPL/2.0
.. _`LICENSE`: LICENSE
.. _`FAQ`: http://www.mozilla.org/MPL/2.0/FAQ.html
Source
------
The source code for *pathspec* is available from the GitHub repo
`cpburnz/python-pathspec`_.
.. _`cpburnz/python-pathspec`: https://github.com/cpburnz/python-pathspec
Installation
------------
*pathspec* is available for install through `PyPI`_::
pip install pathspec
*pathspec* can also be built from source. The following packages will be
required:
- `build`_ (>=0.6.0)
*pathspec* can then be built and installed with::
python -m build
pip install dist/pathspec-*-py3-none-any.whl
.. _`PyPI`: http://pypi.python.org/pypi/pathspec
.. _`build`: https://pypi.org/project/build/
Documentation
-------------
Documentation for *pathspec* is available on `Read the Docs`_.
.. _`Read the Docs`: https://python-path-specification.readthedocs.io
Other Languages
---------------
The related project `pathspec-ruby`_ (by *highb*) provides a similar library as
a `Ruby gem`_.
.. _`pathspec-ruby`: https://github.com/highb/pathspec-ruby
.. _`Ruby gem`: https://rubygems.org/gems/pathspec
Change History
==============
0.12.1 (2023-12-10)
-------------------
Bug fixes:
- `Issue #84`_: PathSpec.match_file() returns None since 0.12.0.
.. _`Issue #84`: https://github.com/cpburnz/python-pathspec/issues/84
0.12.0 (2023-12-09)
-------------------
Major changes:
- Dropped support of EOL Python 3.7. See `Pull #82`_.
API changes:
- Signature of protected method `pathspec.pathspec.PathSpec._match_file()` (with a leading underscore) 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:
- `Issue #81`_: GitIgnoreSpec behaviors differ from git.
- `Pull #83`_: Fix ReadTheDocs builds.
Improvements:
- Mark Python 3.12 as supported. See `Pull #82`_.
- 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()`.
.. _`Issue #81`: https://github.com/cpburnz/python-pathspec/issues/81
.. _`Pull #82`: https://github.com/cpburnz/python-pathspec/pull/82
.. _`Pull #83`: https://github.com/cpburnz/python-pathspec/pull/83
0.11.2 (2023-07-28)
-------------------
New features:
- `Issue #80`_: match_files with negated path spec. `pathspec.PathSpec.match_*()` now have a `negate` parameter to make using *.gitignore* logic easier and more efficient.
Bug fixes:
- `Pull #76`_: Add edge case: patterns that end with an escaped space
- `Issue #77`_/`Pull #78`_: Negate with caret symbol as with the exclamation mark.
.. _`Pull #76`: https://github.com/cpburnz/python-pathspec/pull/76
.. _`Issue #77`: https://github.com/cpburnz/python-pathspec/issues/77
.. _`Pull #78`: https://github.com/cpburnz/python-pathspec/pull/78/
.. _`Issue #80`: https://github.com/cpburnz/python-pathspec/issues/80
0.11.1 (2023-03-14)
-------------------
Bug fixes:
- `Issue #74`_: Include directory should override exclude file.
Improvements:
- `Pull #75`_: Fix partially unknown PathLike type.
- Convert `os.PathLike` to a string properly using `os.fspath`.
.. _`Issue #74`: https://github.com/cpburnz/python-pathspec/issues/74
.. _`Pull #75`: https://github.com/cpburnz/python-pathspec/pull/75
0.11.0 (2023-01-24)
-------------------
Major changes:
- Changed build backend to `flit_core.buildapi`_ from `setuptools.build_meta`_. Building with `setuptools` through `setup.py` is still supported for distributions that need it. See `Issue #72`_.
Improvements:
- `Issue #72`_/`Pull #73`_: Please consider switching the build-system to flit_core to ease setuptools bootstrap.
.. _`flit_core.buildapi`: https://flit.pypa.io/en/latest/index.html
.. _`Issue #72`: https://github.com/cpburnz/python-pathspec/issues/72
.. _`Pull #73`: https://github.com/cpburnz/python-pathspec/pull/73
0.10.3 (2022-12-09)
-------------------
New features:
- Added utility function `pathspec.util.append_dir_sep()` to aid in distinguishing between directories and files on the file-system. See `Issue #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.
.. _`Issue #65`: https://github.com/cpburnz/python-pathspec/issues/65
.. _`Issue #66`: https://github.com/cpburnz/python-pathspec/issues/66
.. _`Pull #67`: https://github.com/cpburnz/python-pathspec/pull/67
.. _`Issue #68`: https://github.com/cpburnz/python-pathspec/issues/68
.. _`Issue #70`: https://github.com/cpburnz/python-pathspec/issues/70
.. _`Pull #71`: https://github.com/cpburnz/python-pathspec/pull/71
0.10.2 (2022-11-12)
-------------------
Bug fixes:
- Fix failing tests on Windows.
- Type hint on *root* parameter on `pathspec.pathspec.PathSpec.match_tree_entries()`.
- Type hint on *root* parameter on `pathspec.pathspec.PathSpec.match_tree_files()`.
- Type hint on *root* parameter on `pathspec.util.iter_tree_entries()`.
- Type hint on *root* parameter on `pathspec.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.
.. _`Pull #58`: https://github.com/cpburnz/python-pathspec/pull/58
.. _`Issue #64`: https://github.com/cpburnz/python-pathspec/issues/64
0.10.1 (2022-09-02)
-------------------
Bug fixes:
- Fix documentation on `pathspec.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 using `setup.py`. See `Issue #61`_.
.. _`Pull #60`: https://github.com/cpburnz/python-pathspec/pull/60
.. _`Issue #61`: https://github.com/cpburnz/python-pathspec/issues/61
.. _`Issue #62`: https://github.com/cpburnz/python-pathspec/issues/62
0.10.0 (2022-08-30)
-------------------
Major changes:
- Dropped support of EOL Python 2.7, 3.5, 3.6. See `Issue #47`_.
- The *gitwildmatch* pattern `dir/*` is now handled the same as `dir/`. This means `dir/*` will now match all descendants rather than only direct children. See `Issue #19`_.
- Added `pathspec.GitIgnoreSpec` class (see new features).
- Changed build system to `pyproject.toml`_ and build backend to `setuptools.build_meta`_ which may have unforeseen consequences.
- Renamed GitHub project from `python-path-specification`_ to `python-pathspec`_. See `Issue #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 for `pathspec.util.iter_tree_files()`.
- Deprecated: `pathspec.iter_tree()` is an alias for `pathspec.util.iter_tree_files()`.
- Deprecated: `pathspec.pattern.Pattern.match()` is no longer used. Use or implement
`pathspec.pattern.Pattern.match_file()`.
New features:
- Added class `pathspec.gitignore.GitIgnoreSpec` (with alias `pathspec.GitIgnoreSpec`) to implement *gitignore* behavior not possible with standard `PathSpec` class. The particular *gitignore* behavior 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 config
- `Issue #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.
.. _`python-path-specification`: https://github.com/cpburnz/python-path-specification
.. _`python-pathspec`: https://github.com/cpburnz/python-pathspec
.. _`pyproject.toml`: https://pip.pypa.io/en/stable/reference/build-system/pyproject-toml/
.. _`setuptools.build_meta`: https://setuptools.pypa.io/en/latest/build_meta.html
.. _`Issue #19`: https://github.com/cpburnz/python-pathspec/issues/19
.. _`Issue #35`: https://github.com/cpburnz/python-pathspec/issues/35
.. _`Issue #41`: https://github.com/cpburnz/python-pathspec/issues/41
.. _`Issue #47`: https://github.com/cpburnz/python-pathspec/issues/47
.. _`Pull #51`: https://github.com/cpburnz/python-pathspec/pull/51
.. _`Issue #52`: https://github.com/cpburnz/python-pathspec/issues/52
.. _`Issue #53`: https://github.com/cpburnz/python-pathspec/issues/53
.. _`Issue #54`: https://github.com/cpburnz/python-pathspec/issues/54
.. _`Issue #55`: https://github.com/cpburnz/python-pathspec/issues/55
.. _`Pull #56`: https://github.com/cpburnz/python-pathspec/pull/56
.. _`Issue #57`: https://github.com/cpburnz/python-pathspec/issues/57
0.9.0 (2021-07-17)
------------------
- `Issue #44`_/`Pull #50`_: Raise `GitWildMatchPatternError` for 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 a `Dict[str, List[pathlike]]` instead of a `Dict[str, pathlike]`.
- Added type hinting.
.. _`Issue #44`: https://github.com/cpburnz/python-pathspec/issues/44
.. _`Pull #45`: https://github.com/cpburnz/python-pathspec/pull/45
.. _`Issue #46`: https://github.com/cpburnz/python-pathspec/issues/46
.. _`Pull #50`: https://github.com/cpburnz/python-pathspec/pull/50
0.8.1 (2020-11-07)
------------------
- `Pull #43`_: Add support for addition operator.
.. _`Pull #43`: https://github.com/cpburnz/python-pathspec/pull/43
0.8.0 (2020-04-09)
------------------
- `Issue #30`_: Expose what patterns matched paths. Added `util.detailed_match_files()`.
- `Issue #31`_: `match_tree()` doesn't return symlinks.
- `Issue #34`_: Support `pathlib.Path`\ s.
- Add `PathSpec.match_tree_entries` and `util.iter_tree_entries()` to support directories and symlinks.
- API change: `match_tree()` has been renamed to `match_tree_files()`. The old name `match_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.
.. _`Issue #30`: https://github.com/cpburnz/python-pathspec/issues/30
.. _`Issue #31`: https://github.com/cpburnz/python-pathspec/issues/31
.. _`Issue #34`: https://github.com/cpburnz/python-pathspec/issues/34
0.7.0 (2019-12-27)
------------------
- `Pull #28`_: Add support for Python 3.8, and drop Python 3.4.
- `Pull #29`_: Publish bdist wheel.
.. _`Pull #28`: https://github.com/cpburnz/python-pathspec/pull/28
.. _`Pull #29`: https://github.com/cpburnz/python-pathspec/pull/29
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.
.. _`Pull #24`: https://github.com/cpburnz/python-pathspec/pull/24
.. _`Pull #25`: https://github.com/cpburnz/python-pathspec/pull/25
.. _`Pull #26`: https://github.com/cpburnz/python-pathspec/pull/26
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.
.. _`Issue #22`: https://github.com/cpburnz/python-pathspec/issues/22
0.5.7 (2018-08-14)
------------------
- `Issue #21`_: Fix collections deprecation warning.
.. _`Issue #21`: https://github.com/cpburnz/python-pathspec/issues/21
0.5.6 (2018-04-06)
------------------
- Improved unit tests.
- Improved type checking.
- `Issue #20`_: Support current directory prefix.
.. _`Issue #20`: https://github.com/cpburnz/python-pathspec/issues/20
0.5.5 (2017-09-09)
------------------
- Add documentation link to README.
0.5.4 (2017-09-09)
------------------
- `Pull #17`_: Add link to Ruby implementation of *pathspec*.
- Add sphinx documentation.
.. _`Pull #17`: https://github.com/cpburnz/python-pathspec/pull/17
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.
.. _`Issue #14`: https://github.com/cpburnz/python-pathspec/issues/14
.. _`Pull #15`: https://github.com/cpburnz/python-pathspec/pull/15
.. _`Issue #16`: https://github.com/cpburnz/python-pathspec/issues/16
0.5.2 (2017-04-04)
------------------
- Fixed change log.
0.5.1 (2017-04-04)
------------------
- `Pull #13`_: Add equality methods to `PathSpec` and `RegexPattern`.
.. _`Pull #13`: https://github.com/cpburnz/python-pathspec/pull/13
0.5.0 (2016-08-22)
------------------
- `Issue #12`_: Add `PathSpec.match_file()`.
- Renamed `gitignore.GitIgnorePattern` to `patterns.gitwildmatch.GitWildMatchPattern`.
- Deprecated `gitignore.GitIgnorePattern`.
.. _`Issue #12`: https://github.com/cpburnz/python-pathspec/issues/12
0.4.0 (2016-07-15)
------------------
- `Issue #11`_: Support converting patterns into regular expressions without compiling them.
- API change: Subclasses of `RegexPattern` should implement `pattern_to_regex()`.
.. _`Issue #11`: https://github.com/cpburnz/python-pathspec/issues/11
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.
.. _`Pull #7`: https://github.com/cpburnz/python-pathspec/pull/7
.. _`Pull #8`: https://github.com/cpburnz/python-pathspec/pull/8
.. _`Pull #9`: https://github.com/cpburnz/python-pathspec/pull/9
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()` and `spec.match_files()` now return iterators instead of sets.
.. _`Pull #5`: https://github.com/cpburnz/python-pathspec/pull/5
.. _`Issue #6`: https://github.com/cpburnz/python-pathspec/issues/6
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.
.. _`Pull #3`: https://github.com/cpburnz/python-pathspec/pull/3
.. _`Pull #4`: https://github.com/cpburnz/python-pathspec/pull/4
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.
Raw data
{
"_id": null,
"home_page": "",
"name": "pathspec",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "",
"author": "",
"author_email": "\"Caleb P. Burns\" <cpburnz@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/ca/bc/f35b8446f4531a7cb215605d100cd88b7ac6f44ab3fc94870c120ab3adbf/pathspec-0.12.1.tar.gz",
"platform": null,
"description": "\nPathSpec\n========\n\n*pathspec* is a utility library for pattern matching of file paths. So\nfar this only includes Git's wildmatch pattern matching which itself is\nderived from Rsync's wildmatch. Git uses wildmatch for its `gitignore`_\nfiles.\n\n.. _`gitignore`: http://git-scm.com/docs/gitignore\n\n\nTutorial\n--------\n\nSay you have a \"Projects\" directory and you want to back it up, but only\ncertain files, and ignore others depending on certain conditions::\n\n\t>>> import pathspec\n\t>>> # The gitignore-style patterns for files to select, but we're including\n\t>>> # instead of ignoring.\n\t>>> spec_text = \"\"\"\n\t...\n\t... # This is a comment because the line begins with a hash: \"#\"\n\t...\n\t... # Include several project directories (and all descendants) relative to\n\t... # the current directory. To reference a directory you must end with a\n\t... # slash: \"/\"\n\t... /project-a/\n\t... /project-b/\n\t... /project-c/\n\t...\n\t... # Patterns can be negated by prefixing with exclamation mark: \"!\"\n\t...\n\t... # Ignore temporary files beginning or ending with \"~\" and ending with\n\t... # \".swp\".\n\t... !~*\n\t... !*~\n\t... !*.swp\n\t...\n\t... # These are python projects so ignore compiled python files from\n\t... # testing.\n\t... !*.pyc\n\t...\n\t... # Ignore the build directories but only directly under the project\n\t... # directories.\n\t... !/*/build/\n\t...\n\t... \"\"\"\n\nWe want to use the ``GitWildMatchPattern`` class to compile our patterns. The\n``PathSpec`` class provides an interface around pattern implementations::\n\n\t>>> spec = pathspec.PathSpec.from_lines(pathspec.patterns.GitWildMatchPattern, spec_text.splitlines())\n\nThat may be a mouthful but it allows for additional patterns to be implemented\nin the future without them having to deal with anything but matching the paths\nsent to them. ``GitWildMatchPattern`` is the implementation of the actual\npattern which internally gets converted into a regular expression. ``PathSpec``\nis a simple wrapper around a list of compiled patterns.\n\nTo make things simpler, we can use the registered name for a pattern class\ninstead of always having to provide a reference to the class itself. The\n``GitWildMatchPattern`` class is registered as **gitwildmatch**::\n\n\t>>> spec = pathspec.PathSpec.from_lines('gitwildmatch', spec_text.splitlines())\n\nIf we wanted to manually compile the patterns we can just do the following::\n\n\t>>> patterns = map(pathspec.patterns.GitWildMatchPattern, spec_text.splitlines())\n\t>>> spec = PathSpec(patterns)\n\n``PathSpec.from_lines()`` is simply a class method which does just that.\n\nIf you want to load the patterns from file, you can pass the file instance\ndirectly as well::\n\n\t>>> with open('patterns.list', 'r') as fh:\n\t>>> spec = pathspec.PathSpec.from_lines('gitwildmatch', fh)\n\nYou can perform matching on a whole directory tree with::\n\n\t>>> matches = spec.match_tree('path/to/directory')\n\nOr you can perform matching on a specific set of file paths with::\n\n\t>>> matches = spec.match_files(file_paths)\n\nOr check to see if an individual file matches::\n\n\t>>> is_matched = spec.match_file(file_path)\n\nThere is a specialized class, ``pathspec.GitIgnoreSpec``, which more closely\nimplements the behavior of **gitignore**. This uses ``GitWildMatchPattern``\npattern by default and handles some edge cases differently from the generic\n``PathSpec`` class. ``GitIgnoreSpec`` can be used without specifying the pattern\nfactory::\n\n\t>>> spec = pathspec.GitIgnoreSpec.from_lines(spec_text.splitlines())\n\n\nLicense\n-------\n\n*pathspec* is licensed under the `Mozilla Public License Version 2.0`_. See\n`LICENSE`_ or the `FAQ`_ for more information.\n\nIn summary, you may use *pathspec* with any closed or open source project\nwithout affecting the license of the larger work so long as you:\n\n- give credit where credit is due,\n\n- and release any custom changes made to *pathspec*.\n\n.. _`Mozilla Public License Version 2.0`: http://www.mozilla.org/MPL/2.0\n.. _`LICENSE`: LICENSE\n.. _`FAQ`: http://www.mozilla.org/MPL/2.0/FAQ.html\n\n\nSource\n------\n\nThe source code for *pathspec* is available from the GitHub repo\n`cpburnz/python-pathspec`_.\n\n.. _`cpburnz/python-pathspec`: https://github.com/cpburnz/python-pathspec\n\n\nInstallation\n------------\n\n*pathspec* is available for install through `PyPI`_::\n\n\tpip install pathspec\n\n*pathspec* can also be built from source. The following packages will be\nrequired:\n\n- `build`_ (>=0.6.0)\n\n*pathspec* can then be built and installed with::\n\n\tpython -m build\n\tpip install dist/pathspec-*-py3-none-any.whl\n\n.. _`PyPI`: http://pypi.python.org/pypi/pathspec\n.. _`build`: https://pypi.org/project/build/\n\n\nDocumentation\n-------------\n\nDocumentation for *pathspec* is available on `Read the Docs`_.\n\n.. _`Read the Docs`: https://python-path-specification.readthedocs.io\n\n\nOther Languages\n---------------\n\nThe related project `pathspec-ruby`_ (by *highb*) provides a similar library as\na `Ruby gem`_.\n\n.. _`pathspec-ruby`: https://github.com/highb/pathspec-ruby\n.. _`Ruby gem`: https://rubygems.org/gems/pathspec\n\n\n\nChange History\n==============\n\n\n0.12.1 (2023-12-10)\n-------------------\n\nBug fixes:\n\n- `Issue #84`_: PathSpec.match_file() returns None since 0.12.0.\n\n\n.. _`Issue #84`: https://github.com/cpburnz/python-pathspec/issues/84\n\n\n0.12.0 (2023-12-09)\n-------------------\n\nMajor changes:\n\n- Dropped support of EOL Python 3.7. See `Pull #82`_.\n\n\nAPI changes:\n\n- Signature of protected method `pathspec.pathspec.PathSpec._match_file()` (with a leading underscore) 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]]`.\n\nNew features:\n\n- 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).\n- Added `pathspec.pattern.RegexPattern.pattern` attribute which stores the original, uncompiled pattern.\n\nBug fixes:\n\n- `Issue #81`_: GitIgnoreSpec behaviors differ from git.\n- `Pull #83`_: Fix ReadTheDocs builds.\n\nImprovements:\n\n- Mark Python 3.12 as supported. See `Pull #82`_.\n- Improve test debugging.\n- Improve type hint on *on_error* parameter on `pathspec.pathspec.PathSpec.match_tree_entries()`.\n- Improve type hint on *on_error* parameter on `pathspec.util.iter_tree_entries()`.\n\n\n.. _`Issue #81`: https://github.com/cpburnz/python-pathspec/issues/81\n.. _`Pull #82`: https://github.com/cpburnz/python-pathspec/pull/82\n.. _`Pull #83`: https://github.com/cpburnz/python-pathspec/pull/83\n\n\n0.11.2 (2023-07-28)\n-------------------\n\nNew features:\n\n- `Issue #80`_: match_files with negated path spec. `pathspec.PathSpec.match_*()` now have a `negate` parameter to make using *.gitignore* logic easier and more efficient.\n\nBug fixes:\n\n- `Pull #76`_: Add edge case: patterns that end with an escaped space\n- `Issue #77`_/`Pull #78`_: Negate with caret symbol as with the exclamation mark.\n\n\n.. _`Pull #76`: https://github.com/cpburnz/python-pathspec/pull/76\n.. _`Issue #77`: https://github.com/cpburnz/python-pathspec/issues/77\n.. _`Pull #78`: https://github.com/cpburnz/python-pathspec/pull/78/\n.. _`Issue #80`: https://github.com/cpburnz/python-pathspec/issues/80\n\n\n0.11.1 (2023-03-14)\n-------------------\n\nBug fixes:\n\n- `Issue #74`_: Include directory should override exclude file.\n\nImprovements:\n\n- `Pull #75`_: Fix partially unknown PathLike type.\n- Convert `os.PathLike` to a string properly using `os.fspath`.\n\n\n.. _`Issue #74`: https://github.com/cpburnz/python-pathspec/issues/74\n.. _`Pull #75`: https://github.com/cpburnz/python-pathspec/pull/75\n\n\n0.11.0 (2023-01-24)\n-------------------\n\nMajor changes:\n\n- Changed build backend to `flit_core.buildapi`_ from `setuptools.build_meta`_. Building with `setuptools` through `setup.py` is still supported for distributions that need it. See `Issue #72`_.\n\nImprovements:\n\n- `Issue #72`_/`Pull #73`_: Please consider switching the build-system to flit_core to ease setuptools bootstrap.\n\n\n.. _`flit_core.buildapi`: https://flit.pypa.io/en/latest/index.html\n.. _`Issue #72`: https://github.com/cpburnz/python-pathspec/issues/72\n.. _`Pull #73`: https://github.com/cpburnz/python-pathspec/pull/73\n\n\n0.10.3 (2022-12-09)\n-------------------\n\nNew features:\n\n- Added utility function `pathspec.util.append_dir_sep()` to aid in distinguishing between directories and files on the file-system. See `Issue #65`_.\n\nBug fixes:\n\n- `Issue #66`_/`Pull #67`_: Package not marked as py.typed.\n- `Issue #68`_: Exports are considered private.\n- `Issue #70`_/`Pull #71`_: 'Self' string literal type is Unknown in pyright.\n\nImprovements:\n\n- `Issue #65`_: Checking directories via match_file() does not work on Path objects.\n\n\n.. _`Issue #65`: https://github.com/cpburnz/python-pathspec/issues/65\n.. _`Issue #66`: https://github.com/cpburnz/python-pathspec/issues/66\n.. _`Pull #67`: https://github.com/cpburnz/python-pathspec/pull/67\n.. _`Issue #68`: https://github.com/cpburnz/python-pathspec/issues/68\n.. _`Issue #70`: https://github.com/cpburnz/python-pathspec/issues/70\n.. _`Pull #71`: https://github.com/cpburnz/python-pathspec/pull/71\n\n\n0.10.2 (2022-11-12)\n-------------------\n\nBug fixes:\n\n- Fix failing tests on Windows.\n- Type hint on *root* parameter on `pathspec.pathspec.PathSpec.match_tree_entries()`.\n- Type hint on *root* parameter on `pathspec.pathspec.PathSpec.match_tree_files()`.\n- Type hint on *root* parameter on `pathspec.util.iter_tree_entries()`.\n- Type hint on *root* parameter on `pathspec.util.iter_tree_files()`.\n- `Issue #64`_: IndexError with my .gitignore file when trying to build a Python package.\n\nImprovements:\n\n- `Pull #58`_: CI: add GitHub Actions test workflow.\n\n\n.. _`Pull #58`: https://github.com/cpburnz/python-pathspec/pull/58\n.. _`Issue #64`: https://github.com/cpburnz/python-pathspec/issues/64\n\n\n0.10.1 (2022-09-02)\n-------------------\n\nBug fixes:\n\n- Fix documentation on `pathspec.pattern.RegexPattern.match_file()`.\n- `Pull #60`_: Remove redundant wheel dep from pyproject.toml.\n- `Issue #61`_: Dist failure for Fedora, CentOS, EPEL.\n- `Issue #62`_: Since version 0.10.0 pure wildcard does not work in some cases.\n\nImprovements:\n\n- Restore support for legacy installations using `setup.py`. See `Issue #61`_.\n\n\n.. _`Pull #60`: https://github.com/cpburnz/python-pathspec/pull/60\n.. _`Issue #61`: https://github.com/cpburnz/python-pathspec/issues/61\n.. _`Issue #62`: https://github.com/cpburnz/python-pathspec/issues/62\n\n\n0.10.0 (2022-08-30)\n-------------------\n\nMajor changes:\n\n- Dropped support of EOL Python 2.7, 3.5, 3.6. See `Issue #47`_.\n- The *gitwildmatch* pattern `dir/*` is now handled the same as `dir/`. This means `dir/*` will now match all descendants rather than only direct children. See `Issue #19`_.\n- Added `pathspec.GitIgnoreSpec` class (see new features).\n- Changed build system to `pyproject.toml`_ and build backend to `setuptools.build_meta`_ which may have unforeseen consequences.\n- Renamed GitHub project from `python-path-specification`_ to `python-pathspec`_. See `Issue #35`_.\n\nAPI changes:\n\n- Deprecated: `pathspec.util.match_files()` is an old function no longer used.\n- Deprecated: `pathspec.match_files()` is an old function no longer used.\n- Deprecated: `pathspec.util.normalize_files()` is no longer used.\n- Deprecated: `pathspec.util.iter_tree()` is an alias for `pathspec.util.iter_tree_files()`.\n- Deprecated: `pathspec.iter_tree()` is an alias for `pathspec.util.iter_tree_files()`.\n-\tDeprecated: `pathspec.pattern.Pattern.match()` is no longer used. Use or implement\n\t`pathspec.pattern.Pattern.match_file()`.\n\nNew features:\n\n- Added class `pathspec.gitignore.GitIgnoreSpec` (with alias `pathspec.GitIgnoreSpec`) to implement *gitignore* behavior not possible with standard `PathSpec` class. The particular *gitignore* behavior implemented is prioritizing patterns matching the file directly over matching an ancestor directory.\n\nBug fixes:\n\n- `Issue #19`_: Files inside an ignored sub-directory are not matched.\n- `Issue #41`_: Incorrectly (?) matches files inside directories that do match.\n- `Pull #51`_: Refactor deprecated unittest aliases for Python 3.11 compatibility.\n- `Issue #53`_: Symlink pathspec_meta.py breaks Windows.\n- `Issue #54`_: test_util.py uses os.symlink which can fail on Windows.\n- `Issue #55`_: Backslashes at start of pattern not handled correctly.\n- `Pull #56`_: pyproject.toml: include subpackages in setuptools config\n- `Issue #57`_: `!` doesn't exclude files in directories if the pattern doesn't have a trailing slash.\n\nImprovements:\n\n- Support Python 3.10, 3.11.\n- Modernize code to Python 3.7.\n- `Issue #52`_: match_files() is not a pure generator function, and it impacts tree_*() gravely.\n\n\n.. _`python-path-specification`: https://github.com/cpburnz/python-path-specification\n.. _`python-pathspec`: https://github.com/cpburnz/python-pathspec\n.. _`pyproject.toml`: https://pip.pypa.io/en/stable/reference/build-system/pyproject-toml/\n.. _`setuptools.build_meta`: https://setuptools.pypa.io/en/latest/build_meta.html\n.. _`Issue #19`: https://github.com/cpburnz/python-pathspec/issues/19\n.. _`Issue #35`: https://github.com/cpburnz/python-pathspec/issues/35\n.. _`Issue #41`: https://github.com/cpburnz/python-pathspec/issues/41\n.. _`Issue #47`: https://github.com/cpburnz/python-pathspec/issues/47\n.. _`Pull #51`: https://github.com/cpburnz/python-pathspec/pull/51\n.. _`Issue #52`: https://github.com/cpburnz/python-pathspec/issues/52\n.. _`Issue #53`: https://github.com/cpburnz/python-pathspec/issues/53\n.. _`Issue #54`: https://github.com/cpburnz/python-pathspec/issues/54\n.. _`Issue #55`: https://github.com/cpburnz/python-pathspec/issues/55\n.. _`Pull #56`: https://github.com/cpburnz/python-pathspec/pull/56\n.. _`Issue #57`: https://github.com/cpburnz/python-pathspec/issues/57\n\n\n0.9.0 (2021-07-17)\n------------------\n\n- `Issue #44`_/`Pull #50`_: Raise `GitWildMatchPatternError` for invalid git patterns.\n- `Pull #45`_: Fix for duplicate leading double-asterisk, and edge cases.\n- `Issue #46`_: Fix matching absolute paths.\n- API change: `util.normalize_files()` now returns a `Dict[str, List[pathlike]]` instead of a `Dict[str, pathlike]`.\n- Added type hinting.\n\n.. _`Issue #44`: https://github.com/cpburnz/python-pathspec/issues/44\n.. _`Pull #45`: https://github.com/cpburnz/python-pathspec/pull/45\n.. _`Issue #46`: https://github.com/cpburnz/python-pathspec/issues/46\n.. _`Pull #50`: https://github.com/cpburnz/python-pathspec/pull/50\n\n\n0.8.1 (2020-11-07)\n------------------\n\n- `Pull #43`_: Add support for addition operator.\n\n.. _`Pull #43`: https://github.com/cpburnz/python-pathspec/pull/43\n\n\n0.8.0 (2020-04-09)\n------------------\n\n- `Issue #30`_: Expose what patterns matched paths. Added `util.detailed_match_files()`.\n- `Issue #31`_: `match_tree()` doesn't return symlinks.\n- `Issue #34`_: Support `pathlib.Path`\\ s.\n- Add `PathSpec.match_tree_entries` and `util.iter_tree_entries()` to support directories and symlinks.\n- API change: `match_tree()` has been renamed to `match_tree_files()`. The old name `match_tree()` is still available as an alias.\n- API change: `match_tree_files()` now returns symlinks. This is a bug fix but it will change the returned results.\n\n.. _`Issue #30`: https://github.com/cpburnz/python-pathspec/issues/30\n.. _`Issue #31`: https://github.com/cpburnz/python-pathspec/issues/31\n.. _`Issue #34`: https://github.com/cpburnz/python-pathspec/issues/34\n\n\n0.7.0 (2019-12-27)\n------------------\n\n- `Pull #28`_: Add support for Python 3.8, and drop Python 3.4.\n- `Pull #29`_: Publish bdist wheel.\n\n.. _`Pull #28`: https://github.com/cpburnz/python-pathspec/pull/28\n.. _`Pull #29`: https://github.com/cpburnz/python-pathspec/pull/29\n\n\n0.6.0 (2019-10-03)\n------------------\n\n- `Pull #24`_: Drop support for Python 2.6, 3.2, and 3.3.\n- `Pull #25`_: Update README.rst.\n- `Pull #26`_: Method to escape gitwildmatch.\n\n.. _`Pull #24`: https://github.com/cpburnz/python-pathspec/pull/24\n.. _`Pull #25`: https://github.com/cpburnz/python-pathspec/pull/25\n.. _`Pull #26`: https://github.com/cpburnz/python-pathspec/pull/26\n\n\n0.5.9 (2018-09-15)\n------------------\n\n- Fixed file system error handling.\n\n\n0.5.8 (2018-09-15)\n------------------\n\n- Improved type checking.\n- Created scripts to test Python 2.6 because Tox removed support for it.\n- Improved byte string handling in Python 3.\n- `Issue #22`_: Handle dangling symlinks.\n\n.. _`Issue #22`: https://github.com/cpburnz/python-pathspec/issues/22\n\n\n0.5.7 (2018-08-14)\n------------------\n\n- `Issue #21`_: Fix collections deprecation warning.\n\n.. _`Issue #21`: https://github.com/cpburnz/python-pathspec/issues/21\n\n\n0.5.6 (2018-04-06)\n------------------\n\n- Improved unit tests.\n- Improved type checking.\n- `Issue #20`_: Support current directory prefix.\n\n.. _`Issue #20`: https://github.com/cpburnz/python-pathspec/issues/20\n\n\n0.5.5 (2017-09-09)\n------------------\n\n- Add documentation link to README.\n\n\n0.5.4 (2017-09-09)\n------------------\n\n- `Pull #17`_: Add link to Ruby implementation of *pathspec*.\n- Add sphinx documentation.\n\n.. _`Pull #17`: https://github.com/cpburnz/python-pathspec/pull/17\n\n\n0.5.3 (2017-07-01)\n------------------\n\n- `Issue #14`_: Fix byte strings for Python 3.\n- `Pull #15`_: Include \"LICENSE\" in source package.\n- `Issue #16`_: Support Python 2.6.\n\n.. _`Issue #14`: https://github.com/cpburnz/python-pathspec/issues/14\n.. _`Pull #15`: https://github.com/cpburnz/python-pathspec/pull/15\n.. _`Issue #16`: https://github.com/cpburnz/python-pathspec/issues/16\n\n\n0.5.2 (2017-04-04)\n------------------\n\n- Fixed change log.\n\n\n0.5.1 (2017-04-04)\n------------------\n\n- `Pull #13`_: Add equality methods to `PathSpec` and `RegexPattern`.\n\n.. _`Pull #13`: https://github.com/cpburnz/python-pathspec/pull/13\n\n\n0.5.0 (2016-08-22)\n------------------\n\n- `Issue #12`_: Add `PathSpec.match_file()`.\n- Renamed `gitignore.GitIgnorePattern` to `patterns.gitwildmatch.GitWildMatchPattern`.\n- Deprecated `gitignore.GitIgnorePattern`.\n\n.. _`Issue #12`: https://github.com/cpburnz/python-pathspec/issues/12\n\n\n0.4.0 (2016-07-15)\n------------------\n\n- `Issue #11`_: Support converting patterns into regular expressions without compiling them.\n- API change: Subclasses of `RegexPattern` should implement `pattern_to_regex()`.\n\n.. _`Issue #11`: https://github.com/cpburnz/python-pathspec/issues/11\n\n\n0.3.4 (2015-08-24)\n------------------\n\n- `Pull #7`_: Fixed non-recursive links.\n- `Pull #8`_: Fixed edge cases in gitignore patterns.\n- `Pull #9`_: Fixed minor usage documentation.\n- Fixed recursion detection.\n- Fixed trivial incompatibility with Python 3.2.\n\n.. _`Pull #7`: https://github.com/cpburnz/python-pathspec/pull/7\n.. _`Pull #8`: https://github.com/cpburnz/python-pathspec/pull/8\n.. _`Pull #9`: https://github.com/cpburnz/python-pathspec/pull/9\n\n\n0.3.3 (2014-11-21)\n------------------\n\n- Improved documentation.\n\n\n0.3.2 (2014-11-08)\n------------------\n\n- `Pull #5`_: Use tox for testing.\n- `Issue #6`_: Fixed matching Windows paths.\n- Improved documentation.\n- API change: `spec.match_tree()` and `spec.match_files()` now return iterators instead of sets.\n\n.. _`Pull #5`: https://github.com/cpburnz/python-pathspec/pull/5\n.. _`Issue #6`: https://github.com/cpburnz/python-pathspec/issues/6\n\n\n0.3.1 (2014-09-17)\n------------------\n\n- Updated README.\n\n\n0.3.0 (2014-09-17)\n------------------\n\n- `Pull #3`_: Fixed trailing slash in gitignore patterns.\n- `Pull #4`_: Fixed test for trailing slash in gitignore patterns.\n- Added registered patterns.\n\n.. _`Pull #3`: https://github.com/cpburnz/python-pathspec/pull/3\n.. _`Pull #4`: https://github.com/cpburnz/python-pathspec/pull/4\n\n\n0.2.2 (2013-12-17)\n------------------\n\n- Fixed setup.py.\n\n\n0.2.1 (2013-12-17)\n------------------\n\n- Added tests.\n- Fixed comment gitignore patterns.\n- Fixed relative path gitignore patterns.\n\n\n0.2.0 (2013-12-07)\n------------------\n\n- Initial release.\n\n",
"bugtrack_url": null,
"license": "",
"summary": "Utility library for gitignore style pattern matching of file paths.",
"version": "0.12.1",
"project_urls": {
"Documentation": "https://python-path-specification.readthedocs.io/en/latest/index.html",
"Issue Tracker": "https://github.com/cpburnz/python-pathspec/issues",
"Source Code": "https://github.com/cpburnz/python-pathspec"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "cc20ff623b09d963f88bfde16306a54e12ee5ea43e9b597108672ff3a408aad6",
"md5": "53caa061bbda861c5b4766f41b084ec8",
"sha256": "a0d503e138a4c123b27490a4f7beda6a01c6f288df0e4a8b79c7eb0dc7b4cc08"
},
"downloads": -1,
"filename": "pathspec-0.12.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "53caa061bbda861c5b4766f41b084ec8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 31191,
"upload_time": "2023-12-10T22:30:43",
"upload_time_iso_8601": "2023-12-10T22:30:43.140207Z",
"url": "https://files.pythonhosted.org/packages/cc/20/ff623b09d963f88bfde16306a54e12ee5ea43e9b597108672ff3a408aad6/pathspec-0.12.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "cabcf35b8446f4531a7cb215605d100cd88b7ac6f44ab3fc94870c120ab3adbf",
"md5": "2b26ad1981bfa23748e115f00085624c",
"sha256": "a482d51503a1ab33b1c67a6c3813a26953dbdc71c31dacaef9a838c4e29f5712"
},
"downloads": -1,
"filename": "pathspec-0.12.1.tar.gz",
"has_sig": false,
"md5_digest": "2b26ad1981bfa23748e115f00085624c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 51043,
"upload_time": "2023-12-10T22:30:45",
"upload_time_iso_8601": "2023-12-10T22:30:45.000082Z",
"url": "https://files.pythonhosted.org/packages/ca/bc/f35b8446f4531a7cb215605d100cd88b7ac6f44ab3fc94870c120ab3adbf/pathspec-0.12.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-12-10 22:30:45",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "cpburnz",
"github_project": "python-pathspec",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "pathspec"
}
