alluka.abc

Alluka's abstract interfaces.

CallbackSig module-attribute

CallbackSig = collections.Callable[Ellipsis, typing.Union[_CoroT[_T], _T]]

Type-hint of a injector callback.

Note

Dependency dependency injection is recursively supported, meaning that the keyword arguments for a dependency callback may also ask for dependencies themselves.

This may either be a sync or asyc function with dependency injection being available for the callback's keyword arguments but dynamically returning either a coroutine or raw value may lead to errors.

Dependent on the context positional arguments may also be proivded.

UNDEFINED module-attribute

UNDEFINED: typing.Final[Undefined] = Undefined()

Deprecated singleton value used to indicate that a value is undefined

deprecated

This will be removedin v0.2.0.

AsyncSelfInjecting

Bases: abc.ABC, typing.Generic[_CallbackT]

Interface of a class used to make an async self-injecting callback.

Examples:

client = alluka.Client()

@client.as_async_self_injecting
async def callback(database: Database = alluka.inject(type=Database)) -> None:
    ...

__call__ abstractmethod async

__call__(*args, **kwargs)

Call this with the provided arguments and any injected arguments.

PARAMETER	DESCRIPTION
*args	Positional arguments to pass to the callback. TYPE: typing.Any DEFAULT: ()
**kwargs	Keyword arguments to pass to the callback alongside injected arguments. TYPE: typing.Any DEFAULT: {}

RETURNS	DESCRIPTION
_T	The callback's result.

RAISES	DESCRIPTION
alluka.MissingDependencyError	If any of the callback's required type dependencies aren't implemented by the client.

callback property abstractmethod

callback()

The callback this wraps.

Client

Bases: abc.ABC

Abstract interface of a dependency injection client.

as_async_self_injecting abstractmethod

as_async_self_injecting(callback)

Link a function to a client to make it self-injecting.

PARAMETER	DESCRIPTION
callback	The callback to make self-injecting. This may be sync or async. TYPE: CallbackSig

RETURNS	DESCRIPTION
AsyncSelfInjecting	The async self-injecting callback.

as_self_injecting abstractmethod

as_self_injecting(callback)

Link a sync function to a client to make it self-injecting.

Note

This uses sync dependency injection and therefore will lead to errors if any of the callback's dependencies are async.

PARAMETER	DESCRIPTION
callback	The callback to make self-injecting. This must be sync. TYPE: collections.abc.Callable

RETURNS	DESCRIPTION
SelfInjecting	The self-injecting callback.

call_with_async_di abstractmethod async

call_with_async_di(callback, *args, **kwargs)

Call a function with async dependency injection.

PARAMETER	DESCRIPTION
callback	The callback to call. This may be sync or async. TYPE: CallbackSig[_T]
*args	Positional arguments to pass to the callback. TYPE: typing.Any DEFAULT: ()
**kwargs	Keyword arguments to pass to the callback. TYPE: typing.Any DEFAULT: {}

RETURNS	DESCRIPTION
_T	The result of the callback.

RAISES	DESCRIPTION
alluka.MissingDependencyError	If any of the callback's required type dependencies aren't implemented by the client.
alluka.SyncOnlyError	If the callback or any of its callback dependencies are async.

call_with_ctx abstractmethod

call_with_ctx(ctx, callback, *args, **kwargs)

Call a function with an existing DI context.

PARAMETER	DESCRIPTION
ctx	The DI context to call the callback with. This will be used for scoped type injection. TYPE: Context
callback	The callback to call. This must be sync. TYPE: collections.Callable[..., _T]
*args	Positional arguments to pass to the callback. TYPE: typing.Any DEFAULT: ()
**kwargs	Keyword arguments to pass to the callback. TYPE: typing.Any DEFAULT: {}

RETURNS	DESCRIPTION
_T	The result of the callback.

RAISES	DESCRIPTION
alluka.MissingDependencyError	If any of the callback's required type dependencies aren't implemented by the client.
alluka.SyncOnlyError	If the callback or any of its callback dependencies are async.

call_with_ctx_async abstractmethod async

call_with_ctx_async(ctx, callback, *args, **kwargs)

Asynchronously call a function with a pre-existing DI context.

PARAMETER	DESCRIPTION
ctx	The DI context to call the callback with. This will be used for scoped type injection. TYPE: Context
callback	The callback to call. This may be sync or async. TYPE: CallbackSig[_T]
*args	Positional arguments to pass to the callback. TYPE: typing.Any DEFAULT: ()
**kwargs	Keyword arguments to pass to the callback. TYPE: typing.Any DEFAULT: {}

RETURNS	DESCRIPTION
_T	The result of the callback.

RAISES	DESCRIPTION
alluka.MissingDependencyError	If any of the callback's required type dependencies aren't implemented by the client.

call_with_di abstractmethod

call_with_di(callback, *args, **kwargs)

Call a function with sync dependency injection.

PARAMETER	DESCRIPTION
callback	The callback to call. This must be sync. TYPE: collections.Callable[..., _T]
*args	Positional arguments to pass to the callback. TYPE: typing.Any DEFAULT: ()
**kwargs	Keyword arguments to pass to the callback. TYPE: typing.Any DEFAULT: {}

RETURNS	DESCRIPTION
_T	The result of the callback.

RAISES	DESCRIPTION
alluka.MissingDependencyError	If any of the callback's required type dependencies aren't implemented by the client.
alluka.SyncOnlyError	If the callback or any of its callback dependencies are async.

get_callback_override abstractmethod

get_callback_override(callback)

Get the override for a specific injected callback.

PARAMETER	DESCRIPTION
callback	The injected callback to get the override for. TYPE: CallbackSig[_T]

RETURNS	DESCRIPTION
CallbackSig[_T] | None	The override if found, else None.

get_type_dependency abstractmethod

get_type_dependency(type_, /, *, default=UNDEFINED)

Get the implementation for an injected type.

deprecated

Defaulting to alluka.abc.UNDEFINED is deprecated and will be replaced by a KeyError raise in v0.2.0.

PARAMETER	DESCRIPTION
type_	The associated type. TYPE: type[_T]
default	The default value to return if the type is not implemented. TYPE: _UndefinedOr[_DefaultT] DEFAULT: UNDEFINED

RETURNS	DESCRIPTION
_T | _DefaultT | alluka.abc.UNDEFINED	The resolved type if found. If the type isn't implemented then the value of default will be returned if it is provided, else alluka.abc.UNDEFINED.

remove_callback_override abstractmethod

remove_callback_override(callback)

Remove a callback override.

PARAMETER	DESCRIPTION
callback	The injected callback to remove the override for. TYPE: CallbackSig[_T]

RETURNS	DESCRIPTION
Self	The client instance to allow chaining.

RAISES	DESCRIPTION
KeyError	If no override is found for the callback.

remove_type_dependency abstractmethod

remove_type_dependency(type_)

Remove a type dependency.

PARAMETER	DESCRIPTION
type_	The associated type. TYPE: type[typing.Any]

RETURNS	DESCRIPTION
Self	The client instance to allow chaining.

RAISES	DESCRIPTION
KeyError	If type is not registered.

set_callback_override abstractmethod

set_callback_override(callback, override)

Override a specific injected callback.

PARAMETER	DESCRIPTION
callback	The injected callback to override. TYPE: CallbackSig[_T]
override	The callback to use instead. TYPE: CallbackSig[_T]

RETURNS	DESCRIPTION
Self	The client instance to allow chaining.

set_type_dependency abstractmethod

set_type_dependency(type_, value)

Set a callback to be called to resolve a injected type.

PARAMETER	DESCRIPTION
type_	The type of the dependency to add an implementation for. TYPE: type[_T]
value	The value of the dependency. TYPE: _T

RETURNS	DESCRIPTION
Self	The client instance to allow chaining.

Context

Bases: abc.ABC

Abstract interface of an injection context.

cache_result abstractmethod

cache_result(callback, value)

Cache the result of a callback within the scope of this context.

PARAMETER	DESCRIPTION
callback	The callback to cache the result of. TYPE: CallbackSig[_T]
value	The value to cache. TYPE: _T

call_with_async_di abstractmethod async

call_with_async_di(callback, *args, **kwargs)

Asynchronously call a function with the current DI context.

PARAMETER	DESCRIPTION
callback	The callback to call. This may be sync or async. TYPE: CallbackSig[_T]
*args	Positional arguments to pass to the callback. TYPE: typing.Any DEFAULT: ()
**kwargs	Keyword arguments to pass to the callback. TYPE: typing.Any DEFAULT: {}

RETURNS	DESCRIPTION
_T	The result of the callback.

RAISES	DESCRIPTION
alluka.MissingDependencyError	If any of the callback's required type dependencies aren't implemented by the client.

call_with_di abstractmethod

call_with_di(callback, *args, **kwargs)

Call a function with the current DI context.

PARAMETER	DESCRIPTION
callback	The callback to call. This must be sync. TYPE: collections.Callable[..., _T]
*args	Positional arguments to pass to the callback. TYPE: typing.Any DEFAULT: ()
**kwargs	Keyword arguments to pass to the callback. TYPE: typing.Any DEFAULT: {}

RETURNS	DESCRIPTION
_T	The result of the callback.

RAISES	DESCRIPTION
alluka.MissingDependencyError	If any of the callback's required type dependencies aren't implemented by the client.
alluka.SyncOnlyError	If the callback or any of its callback dependencies are async.

get_cached_result abstractmethod

get_cached_result(callback, /, *, default=UNDEFINED)

Get the cached result of a callback.

deprecated

Defaulting to alluka.abc.UNDEFINED is deprecated and will be replaced by a KeyError raise in v0.2.0.

PARAMETER	DESCRIPTION
callback	The callback to get the cached result of. TYPE: CallbackSig[_T]
default	The default value to return if the callback is not cached. TYPE: _UndefinedOr[_DefaultT] DEFAULT: UNDEFINED

RETURNS	DESCRIPTION
_T | _DefaultT | alluka.abc.UNDEFINED	The cached result of the callback if found. If the callback's result hasn't been cached or caching isn't implementing then this will return the value of default if it is provided, else alluka.abc.UNDEFINED.

get_type_dependency abstractmethod

get_type_dependency(type_, /, *, default=UNDEFINED)

Get the implementation for an injected type.

Unlike Client.get_type_dependency, this method may also return context specific implementations of a type.

deprecated

Defaulting to alluka.abc.UNDEFINED is deprecated and will be replaced by a KeyError raise in v0.2.0.

PARAMETER	DESCRIPTION
type_	The associated type. TYPE: type[_T]
default	The default value to return if the type is not implemented. TYPE: _UndefinedOr[_DefaultT] DEFAULT: UNDEFINED

RETURNS	DESCRIPTION
_T | _DefaultT | alluka.abc.UNDEFINED	The resolved type if found. If the type isn't implemented then the value of default will be returned if it is provided, else alluka.abc.UNDEFINED.

injection_client property abstractmethod

injection_client()

Injection client this context is bound to.

SelfInjecting

Bases: abc.ABC, typing.Generic[_SyncCallbackT]

Interface of a class used to make a self-injecting callback.

Note

This executes the callback synchronously and therefore will error if any of the callback's dependencies are async.

Examples:

client = alluka.Client()

@client.as_self_injecting
def callback(database: Database = alluka.inject(type=Database)) -> None:
    ...

__call__ abstractmethod

__call__(*args, **kwargs)

Call this callback with the provided arguments + injected arguments.

PARAMETER	DESCRIPTION
*args	Positional arguments to pass to the callback. TYPE: typing.Any DEFAULT: ()
**kwargs	Keyword arguments to pass to the callback. TYPE: typing.Any DEFAULT: {}

RETURNS	DESCRIPTION
_T	The callback's result.

RAISES	DESCRIPTION
alluka.MissingDependencyError	If any of the callback's required type dependencies aren't implemented by the client.
alluka.SyncOnlyError	If the callback or any of its callback dependencies are async.

callback property abstractmethod

callback()

The callback this wraps.

Undefined

Deprecated type of the UNDEFINED constant.

deprecated

This will be removed in v0.2.0.