Skip to content

topmark.config.resolution.merge

topmark / config / resolution / merge

Layer applicability and merge helpers for config resolution.

This module contains pure helpers that
  • select which config provenance layers apply to a target path
  • merge config provenance layers in stable precedence order
  • build effective per-path mutable config drafts

Layer construction from resolved TOML sources lives in topmark.config.resolution.layers.

merge_layers_globally 

merge_layers_globally(layers)

Merge config provenance layers into one mutable config draft.

Parameters:

Name Type Description Default
layers Iterable[ConfigLayer]

Config provenance layers in stable precedence order.

 required

Returns:

Type Description
MutableConfig

MutableConfig draft produced by
MutableConfig

merging the supplied layers in order.
Source code in src/topmark/config/resolution/merge.py 
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
def merge_layers_globally(layers: Iterable[ConfigLayer]) -> MutableConfig:
    """Merge config provenance layers into one mutable config draft.

    Args:
        layers: Config provenance layers in stable precedence order.

    Returns:
        [`MutableConfig`][topmark.config.model.MutableConfig] draft produced by
        merging the supplied layers in order.
    """
    layer_list: list[ConfigLayer] = list(layers)
    logger.debug("Merging %d config layer(s) into mutable config draft", len(layer_list))

    if not layer_list:
        return mutable_config_from_defaults()

    merged: MutableConfig = layer_list[0].config
    for layer in layer_list[1:]:
        merged = merged.merge_with(layer.config)

    return merged

select_applicable_layers 

select_applicable_layers(layers, path)

Return the config provenance layers that apply to a file path.

Global layers (scope_root is None) always apply. File-backed layers apply only when the target path is within their declared scope root.

Parameters:

Name Type Description Default
layers Iterable[ConfigLayer]

Candidate config provenance layers.

 required
path Path

Target file path for which applicability should be evaluated.

 required

Returns:

Type Description
list[ConfigLayer]

Applicable layers in their original precedence order.
Source code in src/topmark/config/resolution/merge.py 
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
def select_applicable_layers(
    layers: Iterable[ConfigLayer],
    path: Path,
) -> list[ConfigLayer]:
    """Return the config provenance layers that apply to a file path.

    Global layers (`scope_root is None`) always apply. File-backed layers apply
    only when the target path is within their declared scope root.

    Args:
        layers: Candidate config provenance layers.
        path: Target file path for which applicability should be evaluated.

    Returns:
        Applicable layers in their original precedence order.
    """
    resolved_path: Path = path.resolve()
    layer_list: list[ConfigLayer] = list(layers)
    applicable: list[ConfigLayer] = []

    for layer in layer_list:
        scope_root: Path | None = layer.scope_root
        if scope_root is None or _is_within_scope(resolved_path, scope_root):
            applicable.append(layer)

    logger.debug(
        "Selected %d/%d applicable config layer(s) for %s",
        len(applicable),
        len(layer_list),
        resolved_path,
    )

    return applicable

build_effective_config_for_path 

build_effective_config_for_path(layers, path)

Build the effective mutable config for a specific file path.

This helper selects the config provenance layers whose scope applies to the target path, then merges them in stable precedence order using MutableConfig.merge_with().

Parameters:

Name Type Description Default
layers Iterable[ConfigLayer]

Candidate config provenance layers.

 required
path Path

Target file path for which to build the effective config.

 required

Returns:

Type Description
MutableConfig

The merged MutableConfig draft
MutableConfig

applicable to path.
Source code in src/topmark/config/resolution/merge.py 
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
def build_effective_config_for_path(
    layers: Iterable[ConfigLayer],
    path: Path,
) -> MutableConfig:
    """Build the effective mutable config for a specific file path.

    This helper selects the config provenance layers whose scope applies to the
    target path, then merges them in stable precedence order using
    [`MutableConfig.merge_with()`][topmark.config.model.MutableConfig.merge_with].

    Args:
        layers: Candidate config provenance layers.
        path: Target file path for which to build the effective config.

    Returns:
        The merged [`MutableConfig`][topmark.config.model.MutableConfig] draft
        applicable to `path`.
    """
    applicable: list[ConfigLayer] = select_applicable_layers(layers, path)
    draft: MutableConfig = merge_layers_globally(applicable)
    logger.debug(
        "Built effective config for %s from %d applicable layer(s)",
        path.resolve(),
        len(applicable),
    )

    return draft