Skip to content

topmark.config.paths

topmark / config / paths

Pure helpers for path normalization and PatternSource construction.

These utilities centralize the path resolution rules used by config loading and CLI overrides. They do no I/O beyond Path.resolve() and have no imports from the rest of TopMark (except logging/types), which makes them safe to use across modules.

Key behaviors
  • abs_path_from(base, raw): resolve raw against base when relative; always returns an absolute, resolved pathlib.Path.
  • ps_from_config(raw, config_dir): create a PatternSource for a path declared inside a config file, anchoring to that file's directory.
  • ps_from_cli(raw, cwd): same, but for CLI-declared paths, anchoring to the invocation CWD.
  • extend_pattern_sources(dst, items, mk, kind, base): batch-normalize a sequence of raw entries into dst using the provided factory.
Policy recap
  • Globs are evaluated later, relative to relative_to.
  • Files that contain patterns (*_from) are normalized immediately, and each carries a base (usually path.parent) for consistent matching.

abs_path_from 

abs_path_from(base, *, raw)

Return an absolute Path for raw using base if raw is relative.

Source code in src/topmark/config/paths.py 
55
56
57
58
59
60
61
62
63
def abs_path_from(
    base: Path,
    *,
    raw: str | PathLike[str],
) -> Path:
    """Return an absolute Path for *raw* using *base* if *raw* is relative."""
    s = str(raw)
    p = Path(s)
    return (base / p).resolve() if not p.is_absolute() else p.resolve()

pattern_source_from_config 

pattern_source_from_config(raw, config_dir)

Create PatternSource from a config-file-declared path using that file's directory.

Source code in src/topmark/config/paths.py 
66
67
68
69
70
71
72
def pattern_source_from_config(
    raw: str,
    config_dir: Path,
) -> PatternSource:
    """Create PatternSource from a config-file-declared path using that file's directory."""
    p: Path = abs_path_from(config_dir, raw=raw)
    return PatternSource(path=p, base=p.parent)

pattern_source_from_cwd 

pattern_source_from_cwd(raw, cwd)

Create PatternSource from a CLI-declared path using CWD (invocation site).

Source code in src/topmark/config/paths.py 
75
76
77
78
79
80
81
def pattern_source_from_cwd(
    raw: str,
    cwd: Path,
) -> PatternSource:
    """Create PatternSource from a CLI-declared path using CWD (invocation site)."""
    p: Path = abs_path_from(cwd, raw=raw)
    return PatternSource(path=p, base=p.parent)

extend_pattern_sources 

extend_pattern_sources(items, *, dst, mk, kind, base)

Append pattern sources created from items to dst.

Parameters:

Name Type Description Default
items Iterable[str]

Raw pattern declarations to normalize; skipped if falsy.

 required
dst list[PatternSource]

Destination list to extend in-place.

 required
mk Callable[[str, Path], PatternSource]

Factory that materializes a PatternSource given the raw entry and resolution base.

 required
kind str

Human-readable label used for debug logging.

 required
base Path

Directory against which relative entries are resolved.

 required
Source code in src/topmark/config/paths.py 
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
def extend_pattern_sources(
    items: Iterable[str],
    *,
    dst: list[PatternSource],
    mk: Callable[[str, Path], PatternSource],
    kind: str,
    base: Path,
) -> None:
    """Append pattern sources created from ``items`` to ``dst``.

    Args:
        items: Raw pattern declarations to normalize; skipped if falsy.
        dst: Destination list to extend in-place.
        mk: Factory that materializes a ``PatternSource`` given the raw entry and resolution base.
        kind: Human-readable label used for debug logging.
        base: Directory against which relative entries are resolved.
    """
    for raw in items or []:
        ps: PatternSource = mk(raw, base)
        dst.append(ps)
        logger.debug(
            "Normalized %s '%s' against %s -> %s (base=%s)", kind, raw, base, ps.path, ps.base
        )