topmark.config.types

topmark / config / types

Lightweight config types and aliases.

This module hosts stable, import-friendly definitions that other config modules can depend on without risk of circular imports.

Exports

• PatternSource: immutable reference to a file containing patterns (e.g., include/exclude lists) together with the base directory used to interpret relative entries inside that file.

Design notes

• Keep side effects out of this module; it should stay dependency-free (stdlib only) to remain safe for low-level imports.
• Prefer structural typing (ConfigMapping) for CLI/API inputs so the config layer remains decoupled from any specific CLI framework.

PatternSource dataclass

PatternSource(*, path, base)

Reference to a pattern or file list declared in a config source.

This value object captures both the absolute path to the referenced file and the base directory used to interpret the file's contents when it contains relative patterns (e.g., a gitignore-style file).

Attributes:

Name	Type	Description
path	Path	Absolute path to the referenced file (e.g., ".gitignore").
base	Path	Absolute directory used as the matching base for the file's patterns. Typically equals path.parent.

PatternGroup dataclass

PatternGroup(*, patterns, base)

A group of gitignore-style patterns with an interpretation base directory.

This is used for pattern arrays declared in configuration files (e.g. [files].include_patterns / [files].exclude_patterns). Each declaring config file contributes its own group so patterns are evaluated relative to the directory of the declaring file.

The to_pathspec() method compiles these patterns as gitignore-style matchers.

Attributes:

Name	Type	Description
patterns	tuple[str, ...]	The raw patterns exactly as declared.
base	Path	Absolute directory used as the matching base for these patterns.

is_empty

is_empty()

Return True if this group contains no patterns.

Source code in src/topmark/config/types.py

def is_empty(self) -> bool:
    """Return True if this group contains no patterns."""
    return not self.patterns

to_pathspec

to_pathspec()

Compile and return a PathSpec for these patterns.

Source code in src/topmark/config/types.py

def to_pathspec(self) -> GitIgnorePathSpec:
    """Compile and return a PathSpec for these patterns."""
    return _compile_gitignore_pathspec_cached(self.patterns)

OutputTarget

Bases: KeyedStrEnum

Available targets for writing processed file content.

FileWriteStrategy

Bases: KeyedStrEnum

Available strategies for writing file content.

The enum .value is the stable machine key used in config and JSON. The human label lives in .label.

compile_gitignore_pathspec

compile_gitignore_pathspec(patterns)

Compile gitignore-style patterns into a PathSpec.

This centralizes PathSpec.from_lines(GitIgnoreBasicPattern, ...) usage so all pattern compilation shares the same semantics.

Note

Internally this function uses an LRU cache keyed by the pattern tuple.

Parameters:

Name	Type	Description	Default
patterns	Iterable[str]	Iterable of gitignore-style patterns.	required

Returns:

Type	Description
GitIgnorePathSpec	Compiled PathSpec matcher.

Source code in src/topmark/config/types.py

def compile_gitignore_pathspec(patterns: Iterable[str]) -> GitIgnorePathSpec:
    """Compile gitignore-style patterns into a `PathSpec`.

    This centralizes `PathSpec.from_lines(GitIgnoreBasicPattern, ...)` usage so all pattern
    compilation shares the same semantics.

    Note:
        Internally this function uses an LRU cache keyed by the pattern tuple.

    Args:
        patterns: Iterable of gitignore-style patterns.

    Returns:
        Compiled `PathSpec` matcher.
    """
    return _compile_gitignore_pathspec_cached(tuple(patterns))