symfonic.devtools.integrations.model

model

Value types for the integration-adapter boundary checks (T4.2.1).

One :class:AdapterEntry per module in src/symfonic that reaches an optional third-party distribution. The registry of those entries is the optional-import map; :mod:symfonic.devtools.integrations.checks turns it into rules IA-1..IA-5 over the statically scanned source tree.

AdapterEntry dataclass

AdapterEntry(module: str, family: str, kind: AdapterKind, extras: tuple[str, ...], roots: tuple[str, ...], import_style: ImportStyle, port: str, suite: str, extra_hint: str = 'self', notes: str = '')

One registered module that reaches an optional distribution.

IntegrationMap dataclass

IntegrationMap(entries: tuple[AdapterEntry, ...], optional_roots: dict[str, tuple[str, ...]], unpinned_roots: dict[str, str] = dict(), adopter_roots: dict[str, str] = dict(), base_transitive: tuple[str, ...] = (), clean_packages: tuple[str, ...] = (), integration_packages: tuple[str, ...] = ())

The optional-import map.

entries registers every module that reaches an optional distribution; optional_roots names every import root the packaging extras provide (root -> the extras that ship it), which is what makes IA-1 a completeness rule rather than a spot check; base_transitive lists roots that arrive with the base dependencies and therefore cannot be treated as optional however optional they look.

governed_roots property

governed_roots: frozenset[str]

Every root the map governs: optional, unpinned, or adopter-owned.

install_hints

install_hints(entry: AdapterEntry) -> tuple[str, ...]

The strings a caller must be able to read when the extra is gone.

Source code in src/symfonic/devtools/integrations/model.py

def install_hints(self, entry: AdapterEntry) -> tuple[str, ...]:
    """The strings a caller must be able to read when the extra is gone."""
    hints = [f"symfonic-core[{extra}]" for extra in entry.extras]
    hints += [
        self.unpinned_roots[root]
        for root in entry.roots
        if root in self.unpinned_roots
    ]
    return tuple(hints)

owning_package

owning_package(module: str) -> str

The declared package a module's import cost is attributed to.

Source code in src/symfonic/devtools/integrations/model.py

def owning_package(self, module: str) -> str:
    """The declared package a module's import cost is attributed to."""
    best = ""
    for package in (*self.integration_packages, *self.clean_packages):
        covers = module == package or module.startswith(package + ".")
        if covers and len(package) > len(best):
            best = package
    return best

root_of

root_of(target: str) -> str | None

The governed root an import target belongs to, if any.

Dotted roots (langgraph.checkpoint.postgres) live in separate optional distributions under a package that is a base dependency, so the longest declared root wins.

Source code in src/symfonic/devtools/integrations/model.py

def root_of(self, target: str) -> str | None:
    """The governed root an import target belongs to, if any.

    Dotted roots (``langgraph.checkpoint.postgres``) live in separate
    optional distributions under a package that is a base dependency,
    so the longest declared root wins.
    """
    best: str | None = None
    for root in self.governed_roots:
        covers = target == root or target.startswith(root + ".")
        if covers and (best is None or len(root) > len(best)):
            best = root
    return best