README.rst
1
2*pathspec*: Path Specification
3==============================
4
5*pathspec* is a utility library for pattern matching of file paths. So
6far this only includes Git's wildmatch pattern matching which itself is
7derived from Rsync's wildmatch. Git uses wildmatch for its `gitignore`_
8files.
9
10.. _`gitignore`: http://git-scm.com/docs/gitignore
11
12
13Tutorial
14--------
15
16Say you have a "Projects" directory and you want to back it up, but only
17certain files, and ignore others depending on certain conditions::
18
19 >>> import pathspec
20 >>> # The gitignore-style patterns for files to select, but we're including
21 >>> # instead of ignoring.
22 >>> spec = """
23 ...
24 ... # This is a comment because the line begins with a hash: "#"
25 ...
26 ... # Include several project directories (and all descendants) relative to
27 ... # the current directory. To reference a directory you must end with a
28 ... # slash: "/"
29 ... /project-a/
30 ... /project-b/
31 ... /project-c/
32 ...
33 ... # Patterns can be negated by prefixing with exclamation mark: "!"
34 ...
35 ... # Ignore temporary files beginning or ending with "~" and ending with
36 ... # ".swp".
37 ... !~*
38 ... !*~
39 ... !*.swp
40 ...
41 ... # These are python projects so ignore compiled python files from
42 ... # testing.
43 ... !*.pyc
44 ...
45 ... # Ignore the build directories but only directly under the project
46 ... # directories.
47 ... !/*/build/
48 ...
49 ... """
50
51We want to use the ``GitWildMatchPattern`` class to compile our patterns. The
52``PathSpec`` class provides an interface around pattern implementations::
53
54 >>> spec = pathspec.PathSpec.from_lines(pathspec.patterns.GitWildMatchPattern, spec.splitlines())
55
56That may be a mouthful but it allows for additional patterns to be implemented
57in the future without them having to deal with anything but matching the paths
58sent to them. ``GitWildMatchPattern`` is the implementation of the actual
59pattern which internally gets converted into a regular expression.
60``PathSpec`` is a simple wrapper around a list of compiled patterns.
61
62To make things simpler, we can use the registered name for a pattern class
63instead of always having to provide a reference to the class itself. The
64``GitWildMatchPattern`` class is registered as **gitwildmatch**::
65
66 >>> spec = pathspec.PathSpec.from_lines('gitwildmatch', spec.splitlines())
67
68If we wanted to manually compile the patterns we can just do the following::
69
70 >>> patterns = map(pathspec.patterns.GitWildMatchPattern, spec.splitlines())
71 >>> spec = PathSpec(patterns)
72
73``PathSpec.from_lines()`` is simply a class method which does just that.
74
75If you want to load the patterns from file, you can pass the file instance
76directly as well::
77
78 >>> with open('patterns.list', 'r') as fh:
79 >>> spec = pathspec.PathSpec.from_lines('gitwildmatch', fh)
80
81You can perform matching on a whole directory tree with::
82
83 >>> matches = spec.match_tree('path/to/directory')
84
85Or you can perform matching on a specific set of file paths with::
86
87 >>> matches = spec.match_files(file_paths)
88
89Or check to see if an individual file matches::
90
91 >>> is_matched = spec.match_file(file_path)
92
93
94License
95-------
96
97*pathspec* is licensed under the `Mozilla Public License Version 2.0`_. See
98`LICENSE`_ or the `FAQ`_ for more information.
99
100In summary, you may use *pathspec* with any closed or open source project
101without affecting the license of the larger work so long as you:
102
103- give credit where credit is due,
104
105- and release any custom changes made to *pathspec*.
106
107.. _`Mozilla Public License Version 2.0`: http://www.mozilla.org/MPL/2.0
108.. _`LICENSE`: LICENSE
109.. _`FAQ`: http://www.mozilla.org/MPL/2.0/FAQ.html
110
111
112Source
113------
114
115The source code for *pathspec* is available from the GitHub repo
116`cpburnz/python-path-specification`_.
117
118.. _`cpburnz/python-path-specification`: https://github.com/cpburnz/python-path-specification
119
120
121Installation
122------------
123
124*pathspec* requires the following packages:
125
126- `setuptools`_
127
128*pathspec* can be installed from source with::
129
130 python setup.py install
131
132*pathspec* is also available for install through `PyPI`_::
133
134 pip install pathspec
135
136.. _`setuptools`: https://pypi.python.org/pypi/setuptools
137.. _`PyPI`: http://pypi.python.org/pypi/pathspec
138
139
140Documentation
141-------------
142
143Documentation for *pathspec* is available on `Read the Docs`_.
144
145.. _`Read the Docs`: http://python-path-specification.readthedocs.io
146
147
148Other Languages
149---------------
150
151*pathspec* is also available as a `Ruby gem`_.
152
153.. _`Ruby gem`: https://github.com/highb/pathspec-ruby
154