alluka#
A type based dependency injection framework for Python 3.9+.
Injected module-attribute
#
Injected = typing.Annotated[_T, InjectedTypes.TYPE]
Type alias used to declare a keyword argument as requiring an injected type.
If a union (e.g. typing.Union[A, B]
, A | B
, typing.Optional[A]
) is passed then each type in the union will be tried separately rather than the literal type, allowing for resolving A | B
to the value set by set_type_dependency(B, ...)
.
If a union has None
as one of its types (including Optional[T]
) then None
will be passed for the parameter if none of the types could be resolved using the linked client.
Note
This is a typing.Annotated alias and the behaviour for nested Annotated types may be found at the docs for it typing.Annotated.
AsyncSelfInjecting #
Bases: alluka.AsyncSelfInjecting[_CallbackSigT]
Class used to link a sync function to a client to make it self-injecting.
Examples:
async def callback(database: Database = alluka.inject(type=Database)) -> None:
await database.do_something()
...
client = alluka.Client()
injecting_callback = alluka.AsyncSelfInjecting(callback, client)
await injecting_callback()
Alternatively alluka.abc.Client.as_async_self_injecting may be used:
client = alluka.Client()
@client.as_async_self_injecting
async def callback(database: Database = alluka.inject(type=Database)) -> None:
...
__init__ #
__init__(client, callback)
Initialise a self injecting callback.
Parameters:
- client (
alluka.Client
) –The injection client to use to resolve dependencies.
- callback (
alluka.abc.CallbackSig
) –The callback to make self-injecting.
This may be sync or async.
Raises:
-
ValueError
–If
callback
has any injected arguments which can only be passed positionally.
BasicContext #
Client #
InjectedDescriptor #
Descriptor used to a declare keyword-argument as requiring an injected dependency.
This is the type returned by alluka.inject.
callback instance-attribute
#
callback: typing.Optional[alluka.CallbackSig[_T]] = callback
The callback to use to resolve the parameter's value.
If this is None
then this is a type dependency.
type instance-attribute
#
type: typing.Optional[_TypeT[_T]] = type
The type to use to resolve the parameter's value.
If both this and callback
are None
, then this is a type dependency and the type will be inferred from the parameter's annotation.
__init__ #
__init__(*, callback=None, type=None)
Initialise an injection default descriptor.
Note
If neither type
or callback
is provided, an injected type will be inferred from the argument's annotation.
Parameters:
- callback (
typing.Optional[alluka.CallbackSig[_T]]
) –The callback to use to resolve the dependency.
If this callback has no type dependencies then this will still work without an injection context but this can be overridden using alluka.abc.Client.set_callback_override.
- type (
typing.Optional[_TypeT[_T]]
) –The type of the dependency to resolve.
If a union (e.g.
typing.Union[A, B]
,A | B
,typing.Optional[A]
) is passed fortype
then each type in the union will be tried separately after the litarl union type is tried, allowing for resolvingA | B
to the value set byset_type_dependency(B, ...)
.If a union has
None
as one of its types (includingOptional[T]
) thenNone
will be passed for the parameter if none of the types could be resolved using the linked client.
Raises:
-
ValueError
–If both
callback
andtype
are provided.
MissingDependencyError #
Bases: AllukaError
Error raised when a dependency couldn't be found.
dependency_type instance-attribute
#
dependency_type: typing.Any = dependency_type
Type of the missing dependency.
SelfInjecting #
Bases: alluka.SelfInjecting[_SyncCallbackT]
Class used to link a sync function to a client to make it self-injecting.
Note
This executes the callback synchronously and therefore will error if any of the callback's dependencies are async.
Examples:
async def callback(database: Database = alluka.inject(type=Database)) -> None:
await database.do_something()
...
client = alluka.Client()
injecting_callback = alluka.SelfInjecting(callback, client)
await injecting_callback()
Alternatively alluka.abc.Client.as_self_injecting may be used:
client = alluka.Client()
@client.as_self_injecting
async def callback(database: Database = alluka.inject(type=Database)) -> None:
...
__init__ #
__init__(client, callback)
Initialise a sync self injecting callback.
Parameters:
- client (
alluka.Client
) –The injection client to use to resolve dependencies.
- callback (
collections.abc.Callable
) –The callback to make self-injecting.
Raises:
-
ValueError
–If
callback
has any injected arguments which can only be passed positionally.
SyncOnlyError #
Bases: AllukaError
Error raised when trying to execute async DI in a sync context.
inject #
inject(*, callback=None, type=None)
Decare a keyword-argument as requiring an injected dependency.
This may be assigned to an arugment's default value to declare injection or as a part of its Annotated metadata.
Note
If neither type
nor callback
is provided, an injected type will be inferred from the argument's annotation.
Examples:
async def callback(
# Here we require an implementation of the type `Component` to be
# injected.
injected_type: Component = alluka.inject(type=Component)
# Here we inject an out-of-scope callback which itself is taking
# advantage of type injectioallukan.
callback_result: ResultT = alluka.inject(callback=injected_callback)
) -> None:
raise NotImplementedError
...
# where client is an `alluka.Client` instance.
result = await client.call_with_async_di(callback)
Parameters:
- callback (
typing.Optional[alluka.CallbackSig[_T]]
) –The callback to use to resolve the dependency.
If this callback has no type dependencies then this will still work without an injection context but this can be overridden using
alluka.abc.Client.set_callback_override
. - type (
typing.Any
) –The type of the dependency to resolve.
If a union (e.g.
typing.Union[A, B]
,A | B
,typing.Optional[A]
) is passed fortype
then each type in the union will be tried separately rather than the literal type, allowing for resolvingA | B
to the value set byset_type_dependency(B, ...)
.If a union has
None
as one of its types (includingOptional[T]
) thenNone
will be passed for the parameter if none of the types could be resolved using the linked client.
Raises:
-
ValueError
–If both
type
andcallback
are provided.