Skip to content

xtr_dependency_injection.bundle

Declaring bundles: the base class, its decorator, and what the decorator records.

KERNEL_BUNDLE module-attribute

KERNEL_BUNDLE: Final = 'kernel'

The core bundle's name: reserved, always active, always first.

BUNDLES_ENTRY_POINT_GROUP module-attribute

BUNDLES_ENTRY_POINT_GROUP: Final = 'xtr_dependency_injection.bundles'

The entry point group a distribution advertises its bundle under.

Bundle

Base class of every bundle; declare one with @as_bundle.

A bundle is built with no arguments — discovery builds it that way — and its hooks run in dependency order: build and prepend_extension while the container is being wired, load_extension while services are defined, process once every bundle loaded, boot and shutdown around the container's life.

Attributes:

  • container (ContainerInterface | None) –

    The container the bundle has been booted against, set by the kernel right before :meth:boot runs. It is None outside a boot/shutdown cycle.

build

build(builder: ContainerBuilder) -> None

Wire the container at compile time. Does nothing by default.

Runs once per build, in bundle order, before any bundle's prepend_extension. Register compiler passes or autoconfiguration rules here.

prepend_extension

prepend_extension(builder: ContainerBuilder) -> None

Adjust other bundles' configs before they are loaded. Does nothing by default.

Call builder.prepend_extension_config(target, transform) for every adjustment.

load_extension

load_extension(config: ConfigT, services: ServiceConfigurator, builder: ContainerBuilder) -> None

Define this bundle's services from its resolved config. Does nothing by default.

process

process(builder: ContainerBuilder) -> None

Inspect and adjust every definition, from every bundle. Does nothing by default.

boot async

boot() -> None

Run once the container is built, before the application. Does nothing by default.

self.container is set by the kernel right before this runs. Fail here, not on first use: bind handlers and check signatures now when that is cheap.

shutdown async

shutdown() -> None

Run as the kernel shuts down, before the container closes. Does nothing by default.

metadata classmethod

metadata() -> BundleMetadata

Return the metadata @as_bundle and @required_bundle recorded on this class.

@required_bundle declarations are merged in at call time so their source order relative to @as_bundle does not matter.

Raises:

  • BundleDefinitionError –

    If the class was not decorated; a subclass of a decorated bundle is a different bundle and needs its own.

NoConfig dataclass

NoConfig()

The config of a bundle that takes none. Never registered, never configurable.

BundleMetadata dataclass

BundleMetadata(name: str, config: type[object], resources: tuple[str, ...] = (), required: tuple[RequiredBundle, ...] = tuple())

A bundle's declaration, as @as_bundle and @required_bundle recorded it.

Attributes:

  • name (str) –

    The name the bundle is known by everywhere.

  • config (type[object]) –

    Its config type; NoConfig when it takes none.

  • resources (tuple[str, ...]) –

    Modules and packages scanned like the application's.

  • required (tuple[RequiredBundle, ...]) –

    The peer bundles it depends on, in decoration order.

AdvertisedBundles dataclass

AdvertisedBundles(bundles: tuple[type[AnyBundle], ...], unusable: tuple[tuple[str, str], ...])

What the entry point group holds: the bundles it yields, and the entries that failed.

Attributes:

  • bundles (tuple[type[AnyBundle], ...]) –

    Every usable bundle class, each once, by entry point name.

  • unusable (tuple[tuple[str, str], ...]) –

    (entry point name, what it said) for each entry that could not be loaded — its module importing a package that is not installed, a name its module does not define, a module that fails as it is imported. A diagnostic shows these rather than leaving the entry unaccounted for.

RequiredBundle dataclass

RequiredBundle(target: str | type[AnyBundle], ignore_on_invalid: bool = False)

One @required_bundle declaration on a bundle class.

Attributes:

  • target (str | type[AnyBundle]) –

    The peer's class, or "module:Class" for lazy import.

  • ignore_on_invalid (bool) –

    When the string target cannot be imported, the resolver reports it as skipped instead of raising.

advertised_bundles

advertised_bundles() -> AdvertisedBundles

Return the advertised bundles, and what each entry that failed to load said.

Loading an entry imports another distribution's module, so call this from a diagnostic, not from a build. A failure is reported, never raised: one broken entry must not hide the rest.