xtr_dependency_injection.decorator ¶
Markers the kernel reads from scanned objects. Each only records; none has behaviour.
Injected
module-attribute
¶
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
¶
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
¶
Fail the build with :class:UnknownServiceError (the default).
IGNORE
class-attribute
instance-attribute
¶
Drop the decorator - it never enters the container.
NULL
class-attribute
instance-attribute
¶
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)whereattributesis a mapping or a callabletype -> 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 isfactory. Its evaluated return type must equal the matched class' key type, else :class:ConfigProviderError.
AutoconfigureTagMarker
dataclass
¶
Autowire
dataclass
¶
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:
paramand :attr:envare given.
Record what to inject; refuse naming both a parameter and a variable.
Target
dataclass
¶
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 ¶
Return the tuple of AliasMarker recorded on obj, or ().
service_of ¶
Return what @as_service recorded on obj, or None.
tagged_item_of ¶
Return what @as_tagged_item recorded on obj, or None.
autoconfigure_of ¶
Return the @autoconfigure marker on obj, or None.
autoconfigure_tag ¶
Record a single tag rule on this class.
Repeatable: several @autoconfigure_tag(...) on one class accumulate.
autoconfigure_tags_of ¶
Return every @autoconfigure_tag marker on obj, in decoration order.
is_container_supplied ¶
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 ¶
Run the decorated function once the bundles have booted; highest priority first.
on_shutdown ¶
Run the decorated function first as the kernel shuts down; highest priority first.
when_not ¶
Leave the decorated object out of the given environments.
Repeating it widens the set. Combined with @when, both must pass.