pathspec


Namepathspec JSON
Version 0.5.0 PyPI version JSON
home_pagehttps://github.com/cpburnz/python-path-specification
SummaryUtility library for gitignore style pattern matching of file paths.
upload_time2016-08-23 02:08:08
maintainerNone
docs_urlNone
authorCaleb P. Burns
requires_pythonNone
licenseMPL 2.0
keywords
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
Coveralis test coverage No Coveralis.
            *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/q
	...
	... """

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

Change History
==============


0.5.0 (2016-08-22)
------------------

- Issue #12: Add `PathSpec.match_file()`.
- Renamed `gitignore.GitIgnorePattern` to `patterns.gitwildmatch.GitWildMatchPattern`.
- Deprecated `gitignore.GitIgnorePattern`.


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()`.


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.


0.3.3 (2014-11-21)
------------------

- Improved documentation.


0.3.2 (2014-11-08)
------------------

- Improved documentation.
- Issue #6: Fixed matching Windows paths.
- API change: `spec.match_tree()` and `spec.match_files()` now return iterators instead of sets.


0.3.1 (2014-09-17)
------------------

- Updated README.


0.3.0 (2014-09-17)
------------------

- Added registered patterns.
- Issue #3: Fixed trailing slash in gitignore patterns.
- Issue #4: Fixed test for trailing slash in gitignore 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.
            

Raw data

            {
    "maintainer": null, 
    "docs_url": null, 
    "requires_python": null, 
    "maintainer_email": null, 
    "cheesecake_code_kwalitee_id": null, 
    "coveralis": false, 
    "keywords": null, 
    "upload_time": "2016-08-23 02:08:08", 
    "author": "Caleb P. Burns", 
    "home_page": "https://github.com/cpburnz/python-path-specification", 
    "github_user": "cpburnz", 
    "download_url": "https://pypi.python.org/packages/67/f6/ad4d6964da803ffe0ec9d513b0be6924be0f502636c17781308561f08034/pathspec-0.5.0.tar.gz", 
    "platform": "UNKNOWN", 
    "version": "0.5.0", 
    "cheesecake_documentation_id": null, 
    "description": "*pathspec*: Path Specification\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 = \"\"\"\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/q\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.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.\n``PathSpec`` is 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.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.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('gitignore', 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\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-path-specification`_.\n\n.. _`cpburnz/python-path-specification`: https://github.com/cpburnz/python-path-specification\n\n\nInstallation\n------------\n\n*pathspec* requires the following packages:\n\n- `setuptools`_\n\n*pathspec* can be installed from source with::\n\n\tpython setup.py install\n\n*pathspec* is also available for install through `PyPI`_::\n\n\tpip install pathspec\n\n.. _`setuptools`: https://pypi.python.org/pypi/setuptools\n.. _`PyPI`: http://pypi.python.org/pypi/pathspec\n\nChange History\n==============\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\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\n0.3.4 (2015-08-24)\n------------------\n\n- Issue #7: Fixed non-recursive links.\n- Issue #8: Fixed edge cases in gitignore patterns.\n- Issue #9: Fixed minor usage documentation.\n- Fixed recursion detection.\n- Fixed trivial incompatibility with Python 3.2.\n\n\n0.3.3 (2014-11-21)\n------------------\n\n- Improved documentation.\n\n\n0.3.2 (2014-11-08)\n------------------\n\n- Improved documentation.\n- Issue #6: Fixed matching Windows paths.\n- API change: `spec.match_tree()` and `spec.match_files()` now return iterators instead of sets.\n\n\n0.3.1 (2014-09-17)\n------------------\n\n- Updated README.\n\n\n0.3.0 (2014-09-17)\n------------------\n\n- Added registered patterns.\n- Issue #3: Fixed trailing slash in gitignore patterns.\n- Issue #4: Fixed test for trailing slash in gitignore patterns.\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.", 
    "tox": true, 
    "lcname": "pathspec", 
    "bugtrack_url": null, 
    "github": true, 
    "name": "pathspec", 
    "license": "MPL 2.0", 
    "travis_ci": false, 
    "github_project": "python-path-specification", 
    "summary": "Utility library for gitignore style pattern matching of file paths.", 
    "split_keywords": [], 
    "author_email": "cpburnz@gmail.com", 
    "urls": [
        {
            "has_sig": false, 
            "upload_time": "2016-08-23T02:08:08", 
            "comment_text": "", 
            "python_version": "source", 
            "url": "https://pypi.python.org/packages/67/f6/ad4d6964da803ffe0ec9d513b0be6924be0f502636c17781308561f08034/pathspec-0.5.0.tar.gz", 
            "md5_digest": "9e7c10d738189b7640a4d58fcb7305cd", 
            "downloads": 0, 
            "filename": "pathspec-0.5.0.tar.gz", 
            "packagetype": "sdist", 
            "path": "67/f6/ad4d6964da803ffe0ec9d513b0be6924be0f502636c17781308561f08034/pathspec-0.5.0.tar.gz", 
            "size": 14277
        }
    ], 
    "_id": null, 
    "cheesecake_installability_id": null
}