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
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
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

render_doctor_report(report)

Render a doctor report as one <dotted_key>: <layer> line per key.

Shared by the CLI doctor command and :class:ConfigDoctorTool so the two provenance renderings cannot drift. Keys are emitted in the report's own (already sorted) order; an empty report renders the empty string.

Source code in packages/axm-config/src/axm_config/doctor.py
Python
76
77
78
79
80
81
82
83
84
85
def render_doctor_report(report: dict[str, dict[str, object]]) -> str:
    """Render a doctor report as one ``<dotted_key>: <layer>`` line per key.

    Shared by the CLI ``doctor`` command and :class:`ConfigDoctorTool` so the
    two provenance renderings cannot drift. Keys are emitted in the report's
    own (already sorted) order; an empty report renders the empty string.
    """
    return "\n".join(
        f"{dotted_key}: {info['layer']}" for dotted_key, info in report.items()
    )