or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.mdpath-matching.mdpattern-system.mdutilities.md
tile.json

tessl/pypi-pathspec

Utility library for gitignore style pattern matching of file paths.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/pathspec@0.12.x

To install, run

npx @tessl/cli install tessl/pypi-pathspec@0.12.0

index.mddocs/

PathSpec

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}")