Registries¶
altar.registry discovers plugins through their entry points. Prefer the typed registry helpers in
altar.models, altar.execution, altar.results and altar.sources; code that needs generic discovery uses
this module. Package and register a plugin explains entry-point groups and manifests.
Stable. The altar.auth, altar.job_queues, altar.connections and altar.registries entry-point groups are
provisional; see Provisional names.
Manifest and run-identity types¶
The manifest and run-identity types are part of altar.models.
Package and register a plugin explains how they are serialized and versioned.
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
¶
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.
PluginRegistry
¶
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 from code; replacement is rejected unless replace=True is explicit.
discover
¶
discover() -> PluginDiscoveryReport[T]
Load every candidate and return healthy plugins plus isolated failures.
all
¶
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
¶
Temporarily replace the process-wide registry map with fresh registries.