Skip to content

symfonic.diagnostics.inspection.extras

extras

Which packaging extra a configured feature needs, and whether it is there.

Three names exist for what an adopter thinks of as one thing, and the whole reason this module exists is that they disagree:

  • the validation token cross-capability rule XV-15 speaks (opentelemetry, spacy),
  • the import root an adapter actually reaches (opentelemetry, spacy, langgraph.checkpoint.postgres),
  • the packaging extra pip installs (otel, entity-linker-spacy, postgres).

Told "telemetry selection requires opentelemetry extra", an adopter runs pip install symfonic-core[opentelemetry] and gets an error, because that extra does not exist. Every row below therefore carries all three names, and tests/diagnostics/inspection/test_extras_registry.py checks each root/extra pair against the repository's optional-import map (T4.2.1) so this table cannot drift into being a second authority. It is a copy for a reason: an installed wheel has no evidence directory to read.

Detection is :func:importlib.util.find_spec, which resolves a module without executing it -- the inspection may not import an adopter's optional stack to find out whether it is installed.

ExtraRequirement dataclass 

ExtraRequirement(import_root: str, packaging_extra: str, trigger: str, token: str | None = None)

One optional distribution a configured feature depends on.

detect_available_roots 

detect_available_roots() -> frozenset[str]

Return every registered import root resolvable in this interpreter.

find_spec on a dotted root imports the parent packages, which is why only registered roots are probed: the set is small, fixed, and reviewed. Any failure to resolve (including a parent package that raises on import) counts as absent, because from the adopter's point of view it is. That is why the guard is Exception and not a list of import-shaped errors: a half-installed optional dependency can raise anything at all from its module body, and a half-installed dependency is precisely what an offline inspection is run to find.

Source code in src/symfonic/diagnostics/inspection/extras.py 
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
def detect_available_roots() -> frozenset[str]:
    """Return every registered import root resolvable in this interpreter.

    ``find_spec`` on a dotted root imports the *parent* packages, which is why
    only registered roots are probed: the set is small, fixed, and reviewed.
    Any failure to resolve (including a parent package that raises on import)
    counts as absent, because from the adopter's point of view it is. That is
    why the guard is ``Exception`` and not a list of import-shaped errors: a
    half-installed optional dependency can raise anything at all from its
    module body, and a half-installed dependency is precisely what an offline
    inspection is run to find.
    """
    found: set[str] = set()
    for root in _BY_ROOT:
        try:
            if importlib.util.find_spec(root) is not None:
                found.add(root)
        except Exception:  # noqa: BLE001 -- probe: any failure means "absent"
            continue
    return frozenset(found)

install_hint 

install_hint(packaging_extra: str) -> str

The exact command that installs packaging_extra, quoted for a shell.

Source code in src/symfonic/diagnostics/inspection/extras.py 
104
105
106
def install_hint(packaging_extra: str) -> str:
    """The exact command that installs *packaging_extra*, quoted for a shell."""
    return f'pip install "symfonic-core[{packaging_extra}]"'

requirement_for_root 

requirement_for_root(import_root: str) -> ExtraRequirement | None

Return the registered requirement for import_root, if any.

Source code in src/symfonic/diagnostics/inspection/extras.py 
 99
100
101
def requirement_for_root(import_root: str) -> ExtraRequirement | None:
    """Return the registered requirement for *import_root*, if any."""
    return _BY_ROOT.get(import_root)