Skip to content

xtr_dependency_injection.decorator

Markers the kernel reads from scanned objects. Each only records; none has behaviour.

Injected module-attribute

Injected: TypeAlias = Annotated[T, Autowire()]

Mark a parameter as container-provided, resolved by its type.

Alias of :data:Annotated[T, Autowire()] <Autowire> — the default autowiring, resolved by the parameter's type annotation.

AutowireDecorated dataclass

AutowireDecorated()

Marks the parameter of a decorator that receives the decorated service.

Applied through Annotated[T, AutowireDecorated()] to the parameter that receives the service the decorator wraps.

OnInvalid

Bases: Enum

What a decorator does when the decorated service is not defined.

:attr:EXCEPTION fails the build, :attr:IGNORE drops the decorator, and :attr:NULL keeps it under the target key with None for its inner parameter.

EXCEPTION class-attribute instance-attribute

EXCEPTION = 'exception'

Fail the build with :class:UnknownServiceError (the default).

IGNORE class-attribute instance-attribute

IGNORE = 'ignore'

Drop the decorator - it never enters the container.

NULL class-attribute instance-attribute

NULL = 'null'

Keep the decorator under the target key; feed None to its inner parameter.

TaggedItemMarker dataclass

TaggedItemMarker(index: Hashable | None = None, priority: int | None = None, before: tuple[type, ...] = tuple(), after: tuple[type, ...] = tuple())

What @as_tagged_item records: the index and ordering constraints of a tagged item.

AutoconfigureMarker dataclass

AutoconfigureMarker(tags: tuple[TagEntry, ...] = (), lifetime: Lifetime | None = None, factory: Callable[..., object] | None = None)

What @autoconfigure records on a class.

Attributes:

  • tags (tuple[TagEntry, ...]) –

    The tags to add to every matched definition. Each entry is either a bare tag name, or (name, attributes) where attributes is a mapping or a callable type -> mapping.

  • lifetime (Lifetime | None) –

    If not None, the lifetime given to matched definitions.

  • factory (Callable[..., object] | None) –

    If not None, matched class definitions become factory definitions whose provider is factory. Its evaluated return type must equal the matched class' key type, else :class:ConfigProviderError.

AutoconfigureTagMarker dataclass

AutoconfigureTagMarker(name: str | None = None, attributes: Mapping[str, object] = (lambda: cast('Mapping[str, object]', {}))())

What one @autoconfigure_tag records — repeatable, one marker per call.

Attributes:

  • name (str | None) –

    The tag name; None means "use the decorated class' qualified_name".

  • attributes (Mapping[str, object]) –

    The attribute mapping to attach to the tag.

Autowire dataclass

Autowire(param: str | None = None, env: str | None = None, **fastapi: object)

Bases: DependencyBase

Mark a parameter as container-provided — by type, by parameter, or from the environment.

Without :attr:param or :attr:env, the parameter is resolved by its type, like :data:Injected. With :attr:param, the named dotted parameter (such as kernel.name) is injected, any environment placeholder in it resolved. With :attr:env, the environment variable expression ("int:PORT", "json:file:SECRETS") is read when the service is built, through the container's processors.

When the web framework is installed the marker is also one of its dependency declarations, so the same annotation resolves through the container inside a route; **fastapi exists for the framework's own copy of a marker and is never written by hand.

Attributes:

  • param (str | None) –

    A dotted parameter name to inject.

  • env (str | None) –

    An environment variable expression to inject.

Raises:

  • ValueError –

    If both :attr:param and :attr:env are given.

Record what to inject; refuse naming both a parameter and a variable.

Target dataclass

Target(name: Hashable, **fastapi: object)

Bases: DependencyBase

Point a container-provided parameter at a specific qualifier.

Names the qualifier the container should resolve for this parameter, when several services of one type live under different qualifiers::

def __init__(self, mailer: Annotated[Mailer, Target("smtp")]) -> None: ...

On its own it marks the parameter as container-provided — no Autowire() needed beside it, though Annotated[T, Autowire(), Target("smtp")] means the same. It cannot sit beside Autowire(param=...) or Autowire(env=...): a parameter is a parameter, an environment variable, or a qualified service.

When the web framework is installed the marker is also one of its dependency declarations, so the same annotation resolves through the container inside a route; **fastapi exists for the framework's own copy of a marker and is never written by hand.

Attributes:

  • name (Hashable) –

    The qualifier of the service to inject.

Record the qualifier the container resolves for this parameter.

aliases_of

aliases_of(obj: object) -> tuple[AliasMarker, ...]

Return the tuple of AliasMarker recorded on obj, or ().

service_of

service_of(obj: object) -> ServiceMarker | None

Return what @as_service recorded on obj, or None.

tagged_item_of

tagged_item_of(obj: object) -> TaggedItemMarker | None

Return what @as_tagged_item recorded on obj, or None.

autoconfigure_of

autoconfigure_of(obj: object) -> AutoconfigureMarker | None

Return the @autoconfigure marker on obj, or None.

autoconfigure_tag

autoconfigure_tag(name: str | None = None, /, **attributes: object) -> Callable[[T], T]

Record a single tag rule on this class.

Repeatable: several @autoconfigure_tag(...) on one class accumulate.

autoconfigure_tags_of

autoconfigure_tags_of(obj: object) -> tuple[AutoconfigureTagMarker, ...]

Return every @autoconfigure_tag marker on obj, in decoration order.

is_container_supplied

is_container_supplied(annotation: object) -> bool

Return whether the container fills a parameter annotated annotation.

True for Injected[T], Annotated[T, Autowire(...)] and Annotated[T, Target(...)] — also as a member of a union, such as Injected[T] | None. Also true for a bare ServiceLocator[T], which the container fills with a lazy name-keyed map of the services of T without a marker, the way it fills a bare Sequence[T] or Mapping[Hashable, T]. A library that calls a user's callable — a command, a message handler — asks this to tell the parameters it passes itself from the ones the container fills, so every such library agrees on what a marker is.

A type alias reads as what it stands for: type Mailer = Injected[Smtp] is container-supplied, as Injected[Smtp] is.

on_boot

on_boot(fn: F) -> F
on_boot(*, priority: int = 0) -> Callable[[F], F]
on_boot(fn: F | None = None, /, *, priority: int = 0) -> F | Callable[[F], F]

Run the decorated function once the bundles have booted; highest priority first.

on_shutdown

on_shutdown(fn: F) -> F
on_shutdown(*, priority: int = 0) -> Callable[[F], F]
on_shutdown(fn: F | None = None, /, *, priority: int = 0) -> F | Callable[[F], F]

Run the decorated function first as the kernel shuts down; highest priority first.

when_not

when_not(env: str, /, *envs: str) -> Callable[[T], T]

Leave the decorated object out of the given environments.

Repeating it widens the set. Combined with @when, both must pass.