tessl/pypi-pathspec

Utility library for gitignore style pattern matching of file paths.

—

Pending

Overview

Eval results

Files

PathSpec

Name: tessl/pypi-pathspec
Author: tessl

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.

Package Information

Package Name: pathspec
Language: Python
Installation: pip install pathspec

Core Imports

import pathspec

Common usage patterns:

from pathspec import PathSpec, GitIgnoreSpec
from pathspec.patterns import GitWildMatchPattern

Direct access to utilities:

from pathspec import iter_tree_files, lookup_pattern, RecursionError

Metadata access:

from pathspec import __version__, __author__, __license__

Type imports:

from typing import AnyStr, Self, Optional, Union, Callable, Iterable, Iterator, Collection, List

Basic Usage

import pathspec

# Create a PathSpec from gitignore-style patterns
patterns = [
    "*.py",           # Include Python files
    "!__pycache__/",  # Exclude cache directories
    "!*.pyc",         # Exclude compiled Python files
    "tests/",         # Include test directories
]

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

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

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

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

For .gitignore-specific behavior:

import pathspec

# GitIgnoreSpec handles gitignore edge cases automatically
gitignore_spec = pathspec.GitIgnoreSpec.from_lines([
    "*.log",
    "temp/",
    "!important.log"
])

# Use exactly like PathSpec
matches = list(gitignore_spec.match_tree_files('/project'))

Architecture

PathSpec is built around several key components:

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

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

Capabilities

Path Matching

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

class PathSpec:
    def __init__(self, patterns: Iterable[Pattern]) -> None: ...
    def match_file(self, file: str, separators: Optional[Collection[str]] = None) -> bool: ...
    def match_files(self, files: Iterable[str], separators: Optional[Collection[str]] = None, *, negate: Optional[bool] = None) -> Iterator[str]: ...
    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]: ...
    def check_file(self, file: str, separators: Optional[Collection[str]] = None) -> CheckResult[str]: ...

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

Path Matching

Pattern System

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

class Pattern:
    def __init__(self, include: Optional[bool]) -> None: ...
    def match_file(self, file: str) -> Optional[Any]: ...

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

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

Pattern System

Utilities

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

def iter_tree_files(root: str, on_error: Optional[Callable[[OSError], None]] = None, follow_links: Optional[bool] = None) -> Iterator[str]: ...
def iter_tree_entries(root: str, on_error: Optional[Callable[[OSError], None]] = None, follow_links: Optional[bool] = None) -> Iterator[TreeEntry]: ...
def normalize_file(file: str, separators: Optional[Collection[str]] = None) -> str: ...

class CheckResult:
    file: str
    include: Optional[bool]
    index: Optional[int]

class TreeEntry:
    name: str
    path: str
    stat: os.stat_result
    def is_dir(self, follow_links: Optional[bool] = None) -> bool: ...
    def is_file(self, follow_links: Optional[bool] = None) -> bool: ...
    def is_symlink(self) -> bool: ...

Utilities

Package Metadata

Package information and version constants.

__version__: str
__author__: str
__copyright__: str
__credits__: List[str]
__license__: str

Error Handling

PathSpec includes specialized exceptions for common error conditions:

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

Common Patterns

File Backup Selection

# Select project files while excluding temporary and build artifacts
backup_patterns = [
    "src/",
    "tests/",
    "*.py",
    "*.md",
    "!*.pyc",
    "!__pycache__/",
    "!.git/",
    "!build/",
    "!dist/"
]

spec = pathspec.PathSpec.from_lines('gitwildmatch', backup_patterns)
files_to_backup = list(spec.match_tree_files('/project'))

Build System Integration

# Get detailed match information for build decisions
spec = pathspec.PathSpec.from_lines('gitwildmatch', build_patterns)
for result in spec.check_tree_files('/src'):
    if result.include:
        print(f"Include {result.file} (matched by pattern {result.index})")
    else:
        print(f"Exclude {result.file}")

Install with Tessl CLI