Package Modules¶
Documentation for findfmt modules and types.
1. Models¶
Core data models and configurations for findfmt.
- class findfmt.models.FileInfo(path: Path, relative_path: Path, tags: frozenset[str] = <factory>, shebang: str | None = None, mime_type: str | None = None, is_executable: bool = False, is_symlink: bool = False, size_bytes: int = 0)[source]¶
Bases:
objectRepresents file metadata, classification tags, and content attributes.
- Variables:
path (pathlib.Path) – Absolute path to the file.
relative_path (pathlib.Path) – Path relative to the traversal root.
tags (frozenset[str]) – Set of tags assigned by the classifier (e.g., ‘python’, ‘text’).
shebang (str | None) – Extracted shebang line if present, otherwise None.
mime_type (str | None) – Detected MIME type if available, otherwise None.
is_executable (bool) – Whether the file has executable permissions.
is_symlink (bool) – Whether the path is a symbolic link.
size_bytes (int) – File size in bytes.
- is_executable: bool¶
- is_symlink: bool¶
- mime_type: str | None¶
- path: Path¶
- relative_path: Path¶
- shebang: str | None¶
- size_bytes: int¶
- tags: frozenset[str]¶
- class findfmt.models.TraversalConfig(root_paths: tuple[~pathlib.Path, ...]=<factory>, include_tags: frozenset[str] = <factory>, exclude_tags: frozenset[str] = <factory>, all_tags: bool = False, shebang_filter: str | None = None, respect_gitignore: bool = True, include_hidden: bool = False, follow_symlinks: bool = False, relative_paths: bool = True, null_delimited: bool = False, show_tags: bool = False, show_summary: bool = False)[source]¶
Bases:
objectConfiguration options for repository traversal and format filtering.
- Variables:
root_paths (tuple[pathlib.Path, ...]) – Roots from which to begin file discovery.
include_tags (frozenset[str]) – Tags that files must have to be included.
exclude_tags (frozenset[str]) – Tags that disqualify a file from inclusion.
all_tags (bool) – If True, file must match all include_tags; if False, any tag.
shebang_filter (str | None) – Substring or interpreter name required in shebang.
respect_gitignore (bool) – Whether to ignore paths matched by gitignore rules.
include_hidden (bool) – Whether to inspect hidden files and directories.
follow_symlinks (bool) – Whether to resolve and traverse symbolic links.
relative_paths (bool) – Whether to output relative paths rather than absolute.
null_delimited (bool) – Whether to delimit output paths with NUL bytes (0).
show_tags (bool) – Whether to print identified tags alongside file paths.
show_summary (bool) – Whether to output summary statistics of matches.
- all_tags: bool¶
- exclude_tags: frozenset[str]¶
- follow_symlinks: bool¶
- include_tags: frozenset[str]¶
- null_delimited: bool¶
- relative_paths: bool¶
- respect_gitignore: bool¶
- root_paths: tuple[Path, ...]¶
- shebang_filter: str | None¶
- show_summary: bool¶
- show_tags: bool¶
2. Classifier¶
File classification and content analysis engine.
- findfmt.classifier.classify_file(path: Path, root_path: Path | None = None) FileInfo[source]¶
Classify a given file path by inspection of name, content, and metadata.
- Parameters:
path – The path of the file to classify.
root_path – Optional root directory used to compute relative_path.
- Returns:
FileInfo containing metadata, identified tags, shebang, and MIME info.
3. Traversal Engine¶
Git-conscious directory traversal and filtering engine.
- findfmt.traversal.find_files(config: TraversalConfig) Iterator[FileInfo][source]¶
Discover and classify files across all configured root paths.
- Parameters:
config – Traversal and filtering configuration.
- Yields:
FileInfo objects matching the criteria.
- findfmt.traversal.load_git_exclude_spec(root: Path) PathSpec[Any] | None[source]¶
Load exclude patterns from .git/info/exclude if present.
- Parameters:
root – Git repository root directory.
- Returns:
PathSpec instance if exclude patterns exist, or None.
- findfmt.traversal.load_gitignore_spec(directory: Path) PathSpec[Any] | None[source]¶
Load gitignore patterns from a directory if a .gitignore file exists.
- Parameters:
directory – Directory to check for .gitignore.
- Returns:
PathSpec instance if rules exist, or None.
- findfmt.traversal.matches_filter(file_info: FileInfo, config: TraversalConfig) bool[source]¶
Determine whether a classified file satisfies traversal filter criteria.
- Parameters:
file_info – The classified FileInfo object.
config – The active TraversalConfig filter settings.
- Returns:
True if the file satisfies all filters, False otherwise.
- findfmt.traversal.should_skip_dir(dir_name: str, *, include_hidden: bool) bool[source]¶
Determine if a directory should be skipped during descent.
- Parameters:
dir_name – Basename of directory.
include_hidden – Whether hidden directories are included.
- Returns:
True if the directory should be skipped, False otherwise.
- findfmt.traversal.traverse_directory(root: Path, config: TraversalConfig, active_specs: tuple[tuple[Path, PathSpecType], ...] = (), base_root: Path | None = None, visited_dirs: set[Path] | None = None) Iterator[FileInfo][source]¶
Recursively traverse a directory hierarchy honoring .gitignore and filters.
- Parameters:
root – The current directory to traverse.
config – Traversal configuration options.
active_specs – Inherited parent gitignore specs with their base paths.
base_root – The top-level root directory used for relative paths.
visited_dirs – Tracked set of canonical directory paths visited to break cycles.
- Yields:
FileInfo objects for matching files in deterministic sorted order.
4. Command-Line Interface¶
Command-line interface for findfmt.
- findfmt.cli.build_parser() ArgumentParser[source]¶
Construct command-line argument parser.
- Returns:
Configured ArgumentParser instance.
- findfmt.cli.get_version() str[source]¶
Retrieve package version or fallback string.
- Returns:
Version string.