Registries

Prefer the typed registry helpers from altar.models, altar.execution, altar.results, and altar.sources. Hosts that need generic discovery can use altar.registry.

Versioned manifest ABI

The immutable manifest and run-identity contracts are part of the stable altar.models façade. See the plugin ABI guide for canonical serialization, compatibility, and migration rules.

Registry

registry

Stable entry-point registry API for extension packages.

Typed helpers such as :func:altar.models.get_model_plugin_registry are preferred when a plugin axis is known. This generic façade is available to hosts that need to inspect or register multiple axes.

CapabilityNotSupported

Bases: NotImplementedError

Raised by an optional plugin method that the adapter deliberately does not implement.

It subclasses NotImplementedError, so an existing except NotImplementedError still catches it. It is a named, catchable signal distinct from a genuinely missing abstract method: a caller probing an optional capability can except CapabilityNotSupported without also swallowing real not-yet-implemented bugs.

DiscoveredPlugin dataclass

DiscoveredPlugin(
    group: str,
    name: str,
    plugin: T,
    source: PluginSource,
    value: str,
    distribution: str | None = None,
    manifest: PluginManifest | None = None,
    replaces: tuple[InstalledPlugin, ...] = (),
)

One loaded and validated plugin plus its provenance.

DuplicateEntryPointError

Bases: PluginRegistryError

Raised when distributions claim the same name in one entry-point group.

InstalledPlugin dataclass

InstalledPlugin(
    group: str, name: str, value: str, distribution: str
)

One installed entry point, described without importing its target.

PluginDiscoveryFailure dataclass

PluginDiscoveryFailure(
    group: str,
    name: str,
    source: PluginSource,
    error_type: str,
    message: str,
    value: str,
    distribution: str | None = None,
)

One isolated discovery failure in a serializable diagnostic shape.

PluginDiscoveryReport dataclass

PluginDiscoveryReport(
    group: str,
    plugins: tuple[DiscoveredPlugin[T], ...],
    failures: tuple[PluginDiscoveryFailure, ...],
)

Validated plugins and per-candidate failures from one discovery pass.

healthy property

healthy: dict[str, T]

Return healthy plugin objects keyed by registry name.

PluginRegistry

PluginRegistry(group: str)

Lazy, validated registry for one canonical Altar entry-point group.

installed

installed() -> tuple[InstalledPlugin, ...]

List installed candidates from metadata without importing plugin modules.

register

register(
    name: str, obj: T, *, replace: bool = False
) -> None

Register from code; replacement is rejected unless replace=True is explicit.

names

names() -> list[str]

List candidate names without importing entry-point targets.

get

get(name: str) -> T

Resolve and validate one plugin without importing unrelated candidates.

discover

discover() -> PluginDiscoveryReport[T]

Load every candidate and return healthy plugins plus isolated failures.

all

all() -> dict[str, T]

Return all healthy plugins; inspect discover().failures for rejected candidates.

PluginRegistryError

Bases: RuntimeError

Base class for registration, discovery, and validation failures.

PluginValidationError

Bases: PluginRegistryError

Raised when a loaded object does not satisfy its entry-point group contract.

ProgrammaticRegistrationError

Bases: PluginRegistryError

Raised when code attempts an implicit replacement or duplicate registration.

get_registry

get_registry(group: str) -> PluginRegistry[Any]

Return the process-wide registry for group.

isolated_registries

isolated_registries() -> Iterator[None]

Temporarily replace the process-wide registry map with fresh registries.