0
# PathSpec
1

2
PathSpec is a utility library for pattern matching of file paths using Git's wildmatch pattern matching (the style used for .gitignore files). It provides comprehensive file path filtering capabilities with support for include/exclude patterns, directory tree traversal, and detailed matching results.
3

4
## Package Information
5

6
- **Package Name**: pathspec
7
- **Language**: Python
8
- **Installation**: `pip install pathspec`
9

10
## Core Imports
11

12
```python
13
import pathspec
14
```
15

16
Common usage patterns:
17

18
```python
19
from pathspec import PathSpec, GitIgnoreSpec
20
from pathspec.patterns import GitWildMatchPattern
21
```
22

23
Direct access to utilities:
24

25
```python
26
from pathspec import iter_tree_files, lookup_pattern, RecursionError
27
```
28

29
Metadata access:
30

31
```python
32
from pathspec import __version__, __author__, __license__
33
```
34

35
Type imports:
36

37
```python
38
from typing import AnyStr, Self, Optional, Union, Callable, Iterable, Iterator, Collection, List
39
```
40

41
## Basic Usage
42

43
```python
44
import pathspec
45

46
# Create a PathSpec from gitignore-style patterns
47
patterns = [
48
    "*.py",           # Include Python files
49
    "!__pycache__/",  # Exclude cache directories
50
    "!*.pyc",         # Exclude compiled Python files
51
    "tests/",         # Include test directories
52
]
53

54
spec = pathspec.PathSpec.from_lines('gitwildmatch', patterns)
55

56
# Check if a single file matches
57
if spec.match_file('example.py'):
58
    print("File matches patterns")
59

60
# Get all matching files from a directory tree
61
matches = list(spec.match_tree_files('/path/to/project'))
62

63
# Filter a list of file paths
64
file_paths = ['src/main.py', 'build/temp.pyc', 'tests/test_main.py']
65
matching_files = list(spec.match_files(file_paths))
66
```
67

68
For .gitignore-specific behavior:
69

70
```python
71
import pathspec
72

73
# GitIgnoreSpec handles gitignore edge cases automatically
74
gitignore_spec = pathspec.GitIgnoreSpec.from_lines([
75
    "*.log",
76
    "temp/",
77
    "!important.log"
78
])
79

80
# Use exactly like PathSpec
81
matches = list(gitignore_spec.match_tree_files('/project'))
82
```
83

84
## Architecture
85

86
PathSpec is built around several key components:
87

88
- **Pattern System**: Pluggable pattern implementations with factory registration
89
- **PathSpec Classes**: Main interfaces for pattern matching operations
90
- **Tree Walking**: Efficient directory traversal with configurable error handling
91
- **Result Types**: Detailed match information with pattern source tracking
92

93
The library supports both simple boolean matching and detailed result analysis, making it suitable for basic file filtering and complex build system integration.
94

95
## Capabilities
96

97
### Path Matching
98

99
Core pattern matching functionality for testing files against gitignore-style patterns. Includes both simple boolean tests and detailed result analysis with pattern source tracking.
100

101
```python { .api }
102
class PathSpec:
103
    def __init__(self, patterns: Iterable[Pattern]) -> None: ...
104
    def match_file(self, file: str, separators: Optional[Collection[str]] = None) -> bool: ...
105
    def match_files(self, files: Iterable[str], separators: Optional[Collection[str]] = None, *, negate: Optional[bool] = None) -> Iterator[str]: ...
106
    def match_tree_files(self, root: str, on_error: Optional[Callable[[OSError], None]] = None, follow_links: Optional[bool] = None, *, negate: Optional[bool] = None) -> Iterator[str]: ...
107
    def check_file(self, file: str, separators: Optional[Collection[str]] = None) -> CheckResult[str]: ...
108

109
class GitIgnoreSpec(PathSpec):
110
    @classmethod
111
    def from_lines(cls, lines: Iterable[AnyStr], pattern_factory: Optional[Union[str, Callable[[AnyStr], Pattern]]] = None) -> Self: ...
112
```
113

114
[Path Matching](./path-matching.md)
115

116
### Pattern System
117

118
Extensible pattern implementation system with built-in Git wildmatch support and custom pattern registration capabilities.
119

120
```python { .api }
121
class Pattern:
122
    def __init__(self, include: Optional[bool]) -> None: ...
123
    def match_file(self, file: str) -> Optional[Any]: ...
124

125
class GitWildMatchPattern(RegexPattern):
126
    @classmethod
127
    def pattern_to_regex(cls, pattern: str) -> Tuple[Optional[str], Optional[bool]]: ...
128

129
def lookup_pattern(name: str) -> Callable[[str], Pattern]: ...
130
def register_pattern(name: str, pattern_factory: Callable[[str], Pattern], override: Optional[bool] = None) -> None: ...
131
```
132

133
[Pattern System](./pattern-system.md)
134

135
### Utilities
136

137
File system traversal, path normalization, and helper functions for working with file paths and pattern matching results.
138

139
```python { .api }
140
def iter_tree_files(root: str, on_error: Optional[Callable[[OSError], None]] = None, follow_links: Optional[bool] = None) -> Iterator[str]: ...
141
def iter_tree_entries(root: str, on_error: Optional[Callable[[OSError], None]] = None, follow_links: Optional[bool] = None) -> Iterator[TreeEntry]: ...
142
def normalize_file(file: str, separators: Optional[Collection[str]] = None) -> str: ...
143

144
class CheckResult:
145
    file: str
146
    include: Optional[bool]
147
    index: Optional[int]
148

149
class TreeEntry:
150
    name: str
151
    path: str
152
    stat: os.stat_result
153
    def is_dir(self, follow_links: Optional[bool] = None) -> bool: ...
154
    def is_file(self, follow_links: Optional[bool] = None) -> bool: ...
155
    def is_symlink(self) -> bool: ...
156
```
157

158
[Utilities](./utilities.md)
159

160
### Package Metadata
161

162
Package information and version constants.
163

164
```python { .api }
165
__version__: str
166
__author__: str
167
__copyright__: str
168
__credits__: List[str]
169
__license__: str
170
```
171

172
## Error Handling
173

174
PathSpec includes specialized exceptions for common error conditions:
175

176
- **RecursionError**: Raised when directory recursion is detected during tree walking
177
- **AlreadyRegisteredError**: Raised when attempting to register a pattern factory name that already exists
178
- **GitWildMatchPatternError**: Raised for invalid Git wildmatch patterns
179

180
## Common Patterns
181

182
### File Backup Selection
183

184
```python
185
# Select project files while excluding temporary and build artifacts
186
backup_patterns = [
187
    "src/",
188
    "tests/",
189
    "*.py",
190
    "*.md",
191
    "!*.pyc",
192
    "!__pycache__/",
193
    "!.git/",
194
    "!build/",
195
    "!dist/"
196
]
197

198
spec = pathspec.PathSpec.from_lines('gitwildmatch', backup_patterns)
199
files_to_backup = list(spec.match_tree_files('/project'))
200
```
201

202
### Build System Integration
203

204
```python
205
# Get detailed match information for build decisions
206
spec = pathspec.PathSpec.from_lines('gitwildmatch', build_patterns)
207
for result in spec.check_tree_files('/src'):
208
    if result.include:
209
        print(f"Include {result.file} (matched by pattern {result.index})")
210
    else:
211
        print(f"Exclude {result.file}")
212
```