topmark.toml.resolution

topmark / toml / resolution

TopMark TOML source discovery and per-run TOML resolution helpers.

This module discovers TopMark-relevant TOML settings files in stable same-directory and upward-traversal precedence order, then optionally resolves those sources into a per-run TOML result.

Responsibilities

• discover user-scoped TopMark TOML sources
• discover project/local TOML sources by walking upward from an anchor path
• preserve same-directory precedence between pyproject.toml and topmark.toml
• honor per-directory root = true stop markers while discovering sources
• load discovered TOML sources through split parse
• resolve non-layered TOML settings such as writer preferences and config loading strictness using precedence rules

Typical discovery precedence (lowest -> highest, once later resolved): 1. built-in defaults 2. user-scoped TOML source 3. project/local TOML sources discovered upward from an anchor path 4. explicitly provided extra TOML sources

This module is intentionally separate from topmark.config.resolution. That module owns layered config provenance layers and MutableConfig merge behavior; this module owns TOML-source discovery and TOML-side per-run resolution.

TomlSourceKind module-attribute

TomlSourceKind = Literal['user', 'discovered', 'explicit']

Discovery kind for one resolved TopMark TOML source.

Allowed values

• "user": discovered from the user-scoped config location
• "discovered": found by upward project/local TOML discovery
• "explicit": provided explicitly by the caller

ResolvedTopmarkTomlSource dataclass

ResolvedTopmarkTomlSource(
    *,
    path,
    parsed,
    kind,
    validation_issues,
    load_diagnostics,
)

One TopMark TOML source participating in per-run resolution.

A source may be syntactically invalid or unreadable. Such sources are still preserved as resolved source records so TOML-source diagnostics can be replayed into staged config validation. Only successfully parsed sources contribute layered config fragments and TOML-side settings such as writer options or strict.

Attributes:

Name	Type	Description
path	Path | SyntheticConfigSource	Resolved filesystem path of the TOML source.
parsed	ParsedTopmarkToml | None	Split-parsed TOML source contents, or None when loading or parsing failed.
kind	TomlSourceKind	Discovery class of the source. Allowed values are "user", "discovered", and "explicit".
validation_issues	tuple[TomlValidationIssue, ...]	TOML schema validation issues associated with this source. For failed loads this is empty because no TOML schema validation could run.
load_diagnostics	FrozenDiagnosticLog	Diagnostics produced while loading or parsing the TOML source. This is normally empty for successfully parsed sources and contains a synthetic error for unreadable or invalid TOML files.

ResolvedTopmarkTomlSources dataclass

ResolvedTopmarkTomlSources(
    *, sources, writer_options, strict
)

Resolved TOML-side state across discovered TopMark TOML sources.

Attributes:

Name	Type	Description
sources	list[ResolvedTopmarkTomlSource]	Loaded and split-parsed TopMark TOML source records in stable precedence order (lowest -> highest), excluding built-in defaults.
writer_options	WriterOptions | None	Resolved non-layered writer preferences using highest-precedence non-None wins.
strict	bool | None	Resolved config-loading strictness using highest-precedence non-None wins, optionally overridden by the explicit function argument to resolve_topmark_toml_sources().

resolve_topmark_toml_sources

resolve_topmark_toml_sources(
    input_paths=None,
    extra_config_files=None,
    strict=None,
    no_config=False,
)

Discover, load, and resolve TopMark TOML sources for one run.

This helper resolves TOML-side settings only. It does not construct ConfigLayer objects and does not merge layered config into a MutableConfig.

Precedence order (lowest -> highest): 1. user-scoped TOML source 2. discovered project/local TOML sources (root-most -> nearest) 3. explicit extra TOML sources (in the order provided) 4. explicit strict function argument, if provided

Parameters:

Name	Type	Description	Default
input_paths	Iterable[Path] | None	Optional discovery anchors. The first path is used to pick the project-discovery starting directory. If it points to a file, its parent directory is used. If omitted, discovery falls back to the current working directory.	None
extra_config_files	Iterable[Path] | None	Explicit TOML source files to append after discovered sources. Later files have higher precedence than earlier ones.	None
strict	bool | None	Optional explicit override for resolved config loading strictness.	None
no_config	bool	If True, skip all discovered TOML sources (user + project) and only consider explicit extra TOML sources.	False

Returns:

Type	Description
ResolvedTopmarkTomlSources	The resolved TOML-side state across all successfully loaded sources.

Source code in src/topmark/toml/resolution.py

def resolve_topmark_toml_sources(
    input_paths: Iterable[Path] | None = None,
    extra_config_files: Iterable[Path] | None = None,
    strict: bool | None = None,
    no_config: bool = False,
) -> ResolvedTopmarkTomlSources:
    """Discover, load, and resolve TopMark TOML sources for one run.

    This helper resolves TOML-side settings only. It does not construct
    `ConfigLayer` objects and does not merge layered config into a
    [`MutableConfig`][topmark.config.model.MutableConfig].

    Precedence order (lowest -> highest):
        1. user-scoped TOML source
        2. discovered project/local TOML sources (root-most -> nearest)
        3. explicit extra TOML sources (in the order provided)
        4. explicit `strict` function argument, if provided

    Args:
        input_paths: Optional discovery anchors. The first path is used to pick
            the project-discovery starting directory. If it points to a file,
            its parent directory is used. If omitted, discovery falls back to
            the current working directory.
        extra_config_files: Explicit TOML source files to append after
            discovered sources. Later files have higher precedence than earlier
            ones.
        strict: Optional explicit override for resolved config
            loading strictness.
        no_config: If `True`, skip all discovered TOML sources (user + project)
            and only consider explicit extra TOML sources.

    Returns:
        The resolved TOML-side state across all successfully loaded sources.
    """
    source_entries: list[ResolvedTopmarkTomlSource] = []

    input_path_list: list[Path] = list(input_paths) if input_paths is not None else []
    anchor: Path = input_path_list[0] if input_path_list else Path.cwd()
    if anchor.is_file():
        anchor = anchor.parent
    anchor = anchor.resolve()

    if not no_config:
        user_cfg_path: Path | None = _discover_user_config_file()
        if user_cfg_path is not None:
            _append_loaded_source(source_entries, user_cfg_path, kind="user")

        for cfg_path in _discover_local_config_files(anchor):
            _append_loaded_source(source_entries, cfg_path, kind="discovered")
    else:
        logger.debug("Skipping discovered TOML sources because no_config=True")

    for extra in extra_config_files or ():
        _append_loaded_source(source_entries, Path(extra), kind="explicit")

    resolved_writer: WriterOptions | None = _resolve_writer_options(source_entries)
    resolved_strict: bool | None = _resolve_strict(
        source_entries,
        explicit_override=strict,
    )

    return ResolvedTopmarkTomlSources(
        sources=source_entries,
        writer_options=resolved_writer,
        strict=resolved_strict,
    )