topmark.config.resolution.layers

topmark / config / resolution / layers

Config provenance layer models and construction helpers.

This module defines the immutable provenance objects used during layered config resolution and provides pure helpers to construct ConfigLayer records from resolved TOML sources.

DEFAULT_LAYER_ORIGIN module-attribute

DEFAULT_LAYER_ORIGIN = '<defaults>'

Origin of built-in defaults layer.

DEFAULT_LAYER_PRECEDENCE module-attribute

DEFAULT_LAYER_PRECEDENCE = 0

Stable precedence assigned to the built-in defaults layer.

FIRST_SOURCE_LAYER_PRECEDENCE module-attribute

FIRST_SOURCE_LAYER_PRECEDENCE = 1

Stable precedence assigned to the first non-default resolved TOML source layer.

ConfigLayerKind

Bases: str, Enum

Provenance kinds used during layered config resolution.

ConfigLayer dataclass

ConfigLayer(
    *, origin, scope_root, precedence, kind, config
)

Immutable config provenance layer used during layered resolution.

Attributes:

Name	Type	Description
origin	Path | SyntheticConfigSource	Provenance origin for the layer, either a real config file path or a typed synthetic source marker such as built-in defaults.
scope_root	Path | None	Optional scope root for applicability checks. File-backed layers usually use the containing config directory; synthetic layers such as defaults, CLI, or API layers typically use None.
precedence	int	Stable merge precedence; lower values are applied earlier.
kind	ConfigLayerKind	Provenance kind for the layer.
config	MutableConfig	Parsed layered config fragment contributed by this layer only.

build_config_layers_from_resolved_toml_sources

build_config_layers_from_resolved_toml_sources(sources)

Build config provenance layers from resolved TOML source records.

Parameters:

Name	Type	Description	Default
sources	list[ResolvedTopmarkTomlSource]	Resolved TOML source records in stable precedence order.	required

Returns:

Type	Description
list[ConfigLayer]	Config provenance layers in stable precedence order, including the
list[ConfigLayer]	built-in defaults layer first followed by one layer per resolved TOML
list[ConfigLayer]	source.

Source code in src/topmark/config/resolution/layers.py

def build_config_layers_from_resolved_toml_sources(
    sources: list[ResolvedTopmarkTomlSource],
) -> list[ConfigLayer]:
    """Build config provenance layers from resolved TOML source records.

    Args:
        sources: Resolved TOML source records in stable precedence order.

    Returns:
        Config provenance layers in stable precedence order, including the
        built-in defaults layer first followed by one layer per resolved TOML
        source.
    """
    layers: list[ConfigLayer] = []

    default_layer: ConfigLayer = _make_default_config_layer()
    layers.append(default_layer)
    logger.debug(
        "Added config layer: kind=%s precedence=%d origin=%s scope_root=%s",
        default_layer.kind,
        default_layer.precedence,
        default_layer.origin,
        default_layer.scope_root,
    )

    precedence: int = FIRST_SOURCE_LAYER_PRECEDENCE
    for source in sources:
        if source.parsed is None:
            logger.debug(
                "Skipping config layer for unreadable or invalid TOML source: %s",
                source.path,
            )
            continue
        layer: ConfigLayer = _make_layer_from_layered_toml_table(
            source.path,
            data=source.parsed.layered_config,
            kind=_kind_from_resolved_toml_source(source),
            precedence=precedence,
        )
        layers.append(layer)
        logger.debug(
            "Added config layer: kind=%s precedence=%d origin=%s scope_root=%s",
            layer.kind,
            layer.precedence,
            layer.origin,
            layer.scope_root,
        )
        precedence += 1

    return layers