xtr_dependency_injection.exception ¶
Every error this package raises.
All of them derive from :class:DependencyInjectionError, so one except
catches anything the kernel can go wrong with, and a narrower one handles a
single cause. Each carries the data a caller needs as typed attributes rather
than forcing a message to be parsed.
BuilderFrozenError ¶
Bases: DependencyInjectionError
A definition was changed after compilation; the container would never see it.
Record the operation attempted.
BuilderPhaseError ¶
Bases: DependencyInjectionError
An operation was called outside the phases it belongs to.
scan and autoconfigure only mean something while bundles load:
after that, scanning and autoconfiguration have already run.
Record the operation and the phase it was attempted in.
BundleDefinitionError ¶
Bases: DependencyInjectionError
A bundle is declared in a way the kernel cannot use.
A bad @as_bundle, a class missing it, a reserved name, a bundle or
config type that cannot be built with no arguments, or two active bundles
claiming one config type.
Record the bundle and what is wrong with it.
CacheFileWriteError ¶
Bases: DependencyInjectionError
A cache file could not be written; the filesystem's error is its __cause__.
Attributes:
-
path(Path) –The file that was to be written.
Record the file that could not be written.
CircularBundleDependencyError ¶
Bases: DependencyInjectionError
Bundles depend on each other in a loop: through @required_bundle, or AliasOf.
Record the loop, its first bundle repeated at the end.
ConfigProviderError ¶
Bases: DependencyInjectionError
A configuration or parameters provider cannot be used.
Its signature or return is wrong, it was found too late (by a scan a
bundle requested while loading), it targets NoConfig, it produced a
bad parameter key, or it carries two markers that exclude each other.
Record the provider and what is wrong with it.
ConflictingConfigProvidersError ¶
Bases: DependencyInjectionError
Two base providers of one group replace the same config; neither may silently win.
Record the config type and the competing providers.
ContainerCompilationError ¶
Bases: DependencyInjectionError
The engine refused to compile the container.
Raised by the compiler when the underlying engine reports the definitions
do not form a valid container (e.g. an unresolvable constructor
dependency). The original engine error is available via __cause__;
any origin notes the compiler attached to it are preserved.
Record the engine's message.
DecoratorSignatureError ¶
Bases: DependencyInjectionError
A decorator lacks exactly one AutowireDecorated parameter of the decorated type.
Record the decorator and what is wrong with its signature.
DependencyInjectionError ¶
Bases: Exception
Base class for every error raised by this package.
Catch this to handle anything the kernel can go wrong with; catch a subclass to handle one cause. Every subclass carries the data a caller needs as typed attributes and composes its own message from them.
DetachedVariableConflictError ¶
Bases: DependencyInjectionError
A context variable already registered to start new connections at another value.
Every kernel in a process shares one registry, so the same variable may be registered again — with the same value, which changes nothing. Two values would leave a new connection's start depending on which came last.
Record the variable and the two values it was registered with.
DuplicateBundleError ¶
Bases: DependencyInjectionError
Two bundles, or two entry points, claim one name.
A name identifies a bundle everywhere — in bundle reports, in a config
prepend, in kernel.bundles — so it must mean one thing.
Record the name and both claimants.
DuplicateServiceError ¶
Bases: DependencyInjectionError
Two definitions claim one key, and neither is allowed to override the other.
The application overrides a bundle silently; two bundles, or two
application definitions, never do — unless a bundle calls
builder.set_definition on purpose.
Record the key and the origins of both definitions.
EnvPlaceholderError ¶
Bases: DependencyInjectionError
An env(...) placeholder was used as if it were already a value.
A placeholder stands for a variable read when the service needing it is
built. Deciding the container's structure with one — testing it in an
if, embedding a non-scalar in a string, naming an unknown processor
prefix — cannot work, because the value does not exist yet.
Attributes:
-
expression(str) –The placeholder's expression, e.g.
"int:PORT". -
reason(str) –Why it cannot be used there.
Record the expression and why it cannot be used there.
FastapiIntegrationError ¶
Bases: DependencyInjectionError
The web integration cannot serve a request from the container.
Raised when a resolver runs with no attached kernel or no open request scope, and when a second kernel is attached to an application one already serves.
Attributes:
-
reason(str) –What the integration is missing.
Record what the integration is missing.
InvalidArgumentError ¶
Bases: DependencyInjectionError, ValueError
A value this package was given cannot be used as it is.
Also a :class:ValueError, so a caller can catch either this package's
errors as a whole or the built-in.
Attributes:
-
reason(str) –What is wrong with the value.
Record what is wrong with the value.
InvalidArgumentTypeError ¶
Bases: DependencyInjectionError, TypeError
Something this package was given is not of a kind it accepts.
Also a :class:TypeError, so a caller can catch either this package's
errors as a whole or the built-in.
Attributes:
-
reason(str) –What was expected, and what was given.
Record what was expected, and what was given.
InvalidDefinitionError ¶
Bases: DependencyInjectionError
A compiler pass found a definition or alias inconsistent with itself.
Raised before the engine sees the container: a provider that does not
match its kind or key, an unknown lifetime, a kernel.reset tag naming
no method, an alias whose target does not implement it.
Record the key and why its definition is invalid.
InvalidEnvironmentError ¶
Bases: DependencyInjectionError
The environment is not one of the kernel's allowed_envs.
Record the environment asked for and those allowed.
InvalidEnvironmentVariableError ¶
Bases: DependencyInjectionError
A processor or cast refused a variable's value.
The error that refused it is __cause__ only when its own message says
nothing about the value: one that quotes the value — or the path the value
names — is dropped, so a logged traceback cannot carry a secret.
Attributes:
-
name(str) –The variable, or the expression being processed.
-
cast(str | Callable[..., object]) –The processor prefix (
"int","json"…) or the callable that refused it. -
value(str) –The value refused. Kept out of the message, which is logged: the variable may hold a secret.
Record the variable, the conversion, and the value that failed it.
InvalidParameterTypeError ¶
Bases: DependencyInjectionError
A %name% reference inside a longer string names a value that cannot be embedded.
Attributes:
-
name(str) –The parameter referenced.
-
type_name(str) –The type of its value.
-
value(str) –The string it was embedded in.
Record the parameter, its type, and the string it was embedded in.
KernelAlreadyBootedError ¶
Bases: DependencyInjectionError
boot() was called a second time on one compiled kernel.
Boot hooks run once per container; build the kernel again for another.
Compose the message.
KernelShutDownError ¶
Bases: DependencyInjectionError
The kernel whose container is asked for a service has shut down.
Its singletons were closed when it did, so handing one out — or building a new one nothing would ever close — is refused.
Compose the message.
MissingBundleError ¶
Bases: DependencyInjectionError
A bundle that is required, or listed explicitly, is absent or was skipped.
Record the missing bundle, who needs it, and why it is missing, when known.
MissingEnvironmentVariableError ¶
Bases: DependencyInjectionError
An environment variable a service needs is not set, and has no default.
Record the variable's name.
ParameterCircularReferenceError ¶
Bases: DependencyInjectionError
A %name% reference loops back on itself.
Attributes:
Record the path of the loop.
ParameterConflictError ¶
Bases: DependencyInjectionError
A parameter leaf is set by two sources; parameters merge, they do not override.
Record the parameter's path and the two sources setting it.
ParameterNotFoundError ¶
Bases: DependencyInjectionError, LookupError
No parameter is set for this dotted name.
Raised by :class:ContainerInterface.get_parameter when
:meth:has_parameter is False for the same name, so callers can catch
a LookupError without coupling to this package.
Record the parameter name that is not defined.
ResourceImportError ¶
Bases: DependencyInjectionError
A scanned module failed to import; the original error is its __cause__.
Record the module that failed.
ScopeTeardownTimeoutError ¶
Bases: DependencyInjectionError
Closing a unit's scoped services took longer than it is given.
Each teardown is the code after yield in a scoped factory; one that
never returns — a connection that hangs on close — would otherwise hold
the unit, and whatever waits for it, forever.
Record how long the teardown was given.
ServiceCircularReferenceError ¶
ServiceNotFoundError ¶
Bases: DependencyInjectionError, LookupError
No service is registered under this (type, qualifier) key.
Raised by :class:ContainerInterface.get when :meth:has is False
for the same arguments, so callers can catch a LookupError without
coupling to this package.
Record the key nothing was registered for.
ServiceOrderError ¶
Bases: DependencyInjectionError
The before/after constraints on tagged services cannot be satisfied.
Raised by :func:sort_with_priorities when a constraint contradicts an
explicit priority, when the bounds derived from unprioritised items are
unsatisfiable, or when the constraints form a cycle. reason is the
sorter's message, verbatim.
Record the sorter's message describing what is wrong.
ServiceResolutionError ¶
ServiceResolutionError(key: tuple[type, Hashable | None], reason: str, /, *, advice: str | None = None)
Bases: DependencyInjectionError
The engine failed to build an already-registered service.
Raised by :class:ContainerInterface.get when the service is registered
(:meth:has is true) but the engine could not build it. :attr:reason
is the engine's own message, repeated in this error's message; the
original engine error is available via __cause__. advice names how
this package resolves the service when the engine failed for a reason a
caller can act on (a scoped or transient service requested without a
scope).
Record the key whose resolution failed and the engine's message.
UnitOfWorkClosedError ¶
Bases: DependencyInjectionError
The unit of work a container or a bound call resolves from has exited.
Its scoped services were released when it did, so handing one out — or
building one nothing would ever release — is refused. Work that outlives
the unit it was started in, a task it spawned, opens one of its own with
unit_of_work(container, join=False).
Compose the message.
UnitReadDuringSingletonBuildError ¶
Bases: DependencyInjectionError
A singleton's factory read what belongs to one unit of work.
A singleton is built once and kept by every unit after, so it would hold on to whichever unit — whichever request — happened to build it. Raised in a kernel built in debug mode only; read it where it is used instead, or make the service scoped.
Record what was read.
UnknownConfigTypeError ¶
Bases: DependencyInjectionError
No active bundle owns the config type a provider returns.
inactive_bundle names the bundle that owns it but is excluded or
disabled in this environment — usually the real cause.
Record the provider, its config type, and the inactive owner, if any.
UnknownEnvironmentFolderError ¶
Bases: DependencyInjectionError
A subpackage of config.packages or config.routes is not an allowed environment.
Every such subpackage is an environment folder, imported only in the
environment it is named after; with allowed_envs set, a name outside
them is a folder no build would ever import — most often a typo.
Attributes:
-
folder(str) –The folder's dotted module name.
-
allowed(tuple[str, ...]) –The environments the kernel allows.
Record the folder and the environments it could have been named after.
UnknownLocatorKeyError ¶
Bases: DependencyInjectionError, LookupError
A service locator was asked for a key it does not hold.
Record the key asked for and those the locator holds.
UnknownServiceError ¶
Bases: DependencyInjectionError
replace, remove, decorate or resettable target a key nothing defines.
Record the key and the operation that needed it.