Skip to content

Doctor

doctor

Provenance reporting for resolved config keys (read-only).

:func:config_doctor_data answers "where would this key resolve from?" for every key visible in a namespace, following the resolver's own env > file > default precedence. It is a diagnostic surface: it probes the layers and reports the winning one per key, it never reads a value into a consumer and never mutates any layer.

The set of reported keys is the union of the namespace's section in ~/.axm/config.toml and any environment variables matching the resolver's AXM_<NS>_* naming. For an absent namespace both sources are empty, so the report is {}.

config_doctor_data(namespace=None)

Report the resolution layer of every visible key, read-only.

For namespace, the reported keys are the union of the namespace's config.toml section keys and its AXM_<NS>_* environment keys. When namespace is None, every namespace present in config.toml (or a not-yet-folded legacy file) is reported. Keys are formatted "<ns>.<key>"; each maps to {"layer": env|file|default, "present": bool}. Nothing is mutated.

Source code in packages/axm-config/src/axm_config/doctor.py
Python
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
def config_doctor_data(
    namespace: str | None = None,
) -> dict[str, dict[str, object]]:
    """Report the resolution layer of every visible key, read-only.

    For ``namespace``, the reported keys are the union of the namespace's
    ``config.toml`` section keys and its ``AXM_<NS>_*`` environment keys. When
    ``namespace`` is ``None``, every namespace present in ``config.toml`` (or a
    not-yet-folded legacy file) is reported.
    Keys are formatted ``"<ns>.<key>"``; each maps to
    ``{"layer": env|file|default, "present": bool}``. Nothing is mutated.
    """
    if namespace is not None:
        validate_segment(namespace, kind="namespace")
    namespaces = [namespace] if namespace is not None else _known_namespaces()
    report: dict[str, dict[str, object]] = {}
    for ns in namespaces:
        keys = set(_store.read(ns)) | _env_keys(ns)
        for key in sorted(keys):
            report[f"{ns}.{key}"] = _provenance(ns, key)
    return report