Metadata-Version: 2.1 Name: pathspec Version: 0.5.9 Summary: Utility library for gitignore style pattern matching of file paths. Home-page: https://github.com/cpburnz/python-path-specification Author: Caleb P. Burns Author-email: cpburnz@gmail.com License: MPL 2.0 Platform: UNKNOWN Classifier: Development Status :: 4 - Beta Classifier: Intended Audience :: Developers Classifier: License :: OSI Approved :: Mozilla Public License 2.0 (MPL 2.0) Classifier: Operating System :: OS Independent Classifier: Programming Language :: Python Classifier: Programming Language :: Python :: 2 Classifier: Programming Language :: Python :: 2.6 Classifier: Programming Language :: Python :: 2.7 Classifier: Programming Language :: Python :: 3 Classifier: Programming Language :: Python :: 3.2 Classifier: Programming Language :: Python :: 3.3 Classifier: Programming Language :: Python :: 3.4 Classifier: Programming Language :: Python :: 3.5 Classifier: Programming Language :: Python :: 3.6 Classifier: Programming Language :: Python :: 3.7 Classifier: Programming Language :: Python :: Implementation :: CPython Classifier: Programming Language :: Python :: Implementation :: PyPy Classifier: Topic :: Software Development :: Libraries :: Python Modules Classifier: Topic :: Utilities *pathspec*: Path Specification ============================== *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 = """ ... ... # 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.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.splitlines()) If we wanted to manually compile the patterns we can just do the following:: >>> patterns = map(pathspec.patterns.GitWildMatchPattern, spec.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('gitignore', 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) 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-path-specification`_. .. _`cpburnz/python-path-specification`: https://github.com/cpburnz/python-path-specification Installation ------------ *pathspec* requires the following packages: - `setuptools`_ *pathspec* can be installed from source with:: python setup.py install *pathspec* is also available for install through `PyPI`_:: pip install pathspec .. _`setuptools`: https://pypi.python.org/pypi/setuptools .. _`PyPI`: http://pypi.python.org/pypi/pathspec Documentation ------------- Documentation for *pathspec* is available on `Read the Docs`_. .. _`Read the Docs`: http://python-path-specification.readthedocs.io Other Languages --------------- *pathspec* is also available as a `Ruby gem`_. .. _`Ruby gem`: https://github.com/highb/pathspec-ruby Change History ============== 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-path-specification/issues/22 0.5.7 (2018-08-14) ------------------ - `Issue #21`_: Fix collections deprecation warning. .. _`Issue #21`: https://github.com/cpburnz/python-path-specification/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-path-specification/issues/20 0.5.5 (2017-09-09) ------------------ - Add documentation link to README. 0.5.4 (2017-09-09) ------------------ - `Issue #17`_: Add link to Ruby implementation of *pathspec*. - Add sphinx documentation. .. _`Issue #17`: https://github.com/cpburnz/python-path-specification/pull/17 0.5.3 (2017-07-01) ------------------ - `Issue #14`_: Fix byte strings for Python 3. - `Issue #15`_: Include "LICENSE" in source package. - `Issue #16`_: Support Python 2.6. .. _`Issue #14`: https://github.com/cpburnz/python-path-specification/issues/14 .. _`Issue #15`: https://github.com/cpburnz/python-path-specification/pull/15 .. _`Issue #16`: https://github.com/cpburnz/python-path-specification/issues/16 0.5.2 (2017-04-04) ------------------ - Fixed change log. 0.5.1 (2017-04-04) ------------------ - `Issue #13`_: Add equality methods to `PathSpec` and `RegexPattern`. .. _`Issue #13`: https://github.com/cpburnz/python-path-specification/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-path-specification/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-path-specification/issues/11 0.3.4 (2015-08-24) ------------------ - `Issue #7`_: Fixed non-recursive links. - `Issue #8`_: Fixed edge cases in gitignore patterns. - `Issue #9`_: Fixed minor usage documentation. - Fixed recursion detection. - Fixed trivial incompatibility with Python 3.2. .. _`Issue #7`: https://github.com/cpburnz/python-path-specification/pull/7 .. _`Issue #8`: https://github.com/cpburnz/python-path-specification/pull/8 .. _`Issue #9`: https://github.com/cpburnz/python-path-specification/pull/9 0.3.3 (2014-11-21) ------------------ - Improved documentation. 0.3.2 (2014-11-08) ------------------ - `Issue #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. .. _`Issue #5`: https://github.com/cpburnz/python-path-specification/pull/5 .. _`Issue #6`: https://github.com/cpburnz/python-path-specification/issues/6 0.3.1 (2014-09-17) ------------------ - Updated README. 0.3.0 (2014-09-17) ------------------ - `Issue #3`_: Fixed trailing slash in gitignore patterns. - `Issue #4`_: Fixed test for trailing slash in gitignore patterns. - Added registered patterns. .. _`Issue #3`: https://github.com/cpburnz/python-path-specification/pull/3 .. _`Issue #4`: https://github.com/cpburnz/python-path-specification/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.