alluka.abc#
Alluka's abstract interfaces.
CallbackSig module-attribute
#
CallbackSig = collections.Callable[..., 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.
Parameters:
- *args (
typing.Any
) –Positional arguments to pass to the callback.
- **kwargs (
typing.Any
) –Keyword arguments to pass to the callback alongside injected arguments.
Returns:
-
_T
–The callback's result.
Raises:
-
alluka.MissingDependencyError
–If any of the callback's required type dependencies aren't implemented by the client.
Client #
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.
Parameters:
- callback (
CallbackSig
) –The callback to make self-injecting.
This may be sync or async.
Returns:
-
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.
Parameters:
- callback (
collections.abc.Callable
) –The callback to make self-injecting.
This must be sync.
Returns:
-
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.
Parameters:
- callback (
CallbackSig[_T]
) –The callback to call.
This may be sync or async.
- *args (
typing.Any
) –Positional arguments to pass to the callback.
- **kwargs (
typing.Any
) –Keyword arguments to pass to the callback.
Returns:
-
_T
–The result of the callback.
Raises:
-
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.
Parameters:
- ctx (
Context
) –The DI context to call the callback with.
This will be used for scoped type injection.
- callback (
collections.Callable[..., _T]
) –The callback to call.
This must be sync.
- *args (
typing.Any
) –Positional arguments to pass to the callback.
- **kwargs (
typing.Any
) –Keyword arguments to pass to the callback.
Returns:
-
_T
–The result of the callback.
Raises:
-
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.
Parameters:
- ctx (
Context
) –The DI context to call the callback with.
This will be used for scoped type injection.
- callback (
CallbackSig[_T]
) –The callback to call.
This may be sync or async.
- *args (
typing.Any
) –Positional arguments to pass to the callback.
- **kwargs (
typing.Any
) –Keyword arguments to pass to the callback.
Returns:
-
_T
–The result of the callback.
Raises:
-
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.
Parameters:
- callback (
collections.Callable[..., _T]
) –The callback to call.
This must be sync.
- *args (
typing.Any
) –Positional arguments to pass to the callback.
- **kwargs (
typing.Any
) –Keyword arguments to pass to the callback.
Returns:
-
_T
–The result of the callback.
Raises:
-
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.
Parameters:
- callback (
CallbackSig[_T]
) –The injected callback to get the override for.
Returns:
-
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
.
Parameters:
- type_ (
type[_T]
) –The associated type.
- default (
_UndefinedOr[_DefaultT]
) –The default value to return if the type is not implemented.
Returns:
-
_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.
Parameters:
- callback (
CallbackSig[_T]
) –The injected callback to remove the override for.
Returns:
-
Self
–The client instance to allow chaining.
Raises:
-
KeyError
–If no override is found for the callback.
remove_type_dependency abstractmethod
#
remove_type_dependency(type_)
set_callback_override abstractmethod
#
set_callback_override(callback, override)
Override a specific injected callback.
Parameters:
- callback (
CallbackSig[_T]
) –The injected callback to override.
- override (
CallbackSig[_T]
) –The callback to use instead.
Returns:
-
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.
Parameters:
- type_ (
type[_T]
) –The type of the dependency to add an implementation for.
- value (
_T
) –The value of the dependency.
Returns:
-
Self
–The client instance to allow chaining.
Context #
Abstract interface of an injection context.
injection_client abstractmethod
property
#
injection_client: Client
Injection client this context is bound to.
cache_result abstractmethod
#
cache_result(callback, value)
Cache the result of a callback within the scope of this context.
Parameters:
- callback (
CallbackSig[_T]
) –The callback to cache the result of.
- value (
_T
) –The value to cache.
call_with_async_di abstractmethod
async
#
call_with_async_di(callback, *args, **kwargs)
Asynchronously call a function with the current DI context.
Parameters:
- callback (
CallbackSig[_T]
) –The callback to call.
This may be sync or async.
- *args (
typing.Any
) –Positional arguments to pass to the callback.
- **kwargs (
typing.Any
) –Keyword arguments to pass to the callback.
Returns:
-
_T
–The result of the callback.
Raises:
-
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.
Parameters:
- callback (
collections.Callable[..., _T]
) –The callback to call.
This must be sync.
- *args (
typing.Any
) –Positional arguments to pass to the callback.
- **kwargs (
typing.Any
) –Keyword arguments to pass to the callback.
Returns:
-
_T
–The result of the callback.
Raises:
-
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
.
Parameters:
- callback (
CallbackSig[_T]
) –The callback to get the cached result of.
- default (
_UndefinedOr[_DefaultT]
) –The default value to return if the callback is not cached.
Returns:
-
_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
.
Parameters:
- type_ (
type[_T]
) –The associated type.
- default (
_UndefinedOr[_DefaultT]
) –The default value to return if the type is not implemented.
Returns:
-
_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.
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.
Parameters:
- *args (
typing.Any
) –Positional arguments to pass to the callback.
- **kwargs (
typing.Any
) –Keyword arguments to pass to the callback.
Returns:
-
_T
–The callback's result.
Raises:
-
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.