Skip to content

alluka.abc#

Alluka's abstract interfaces.

CallbackSig module-attribute #

CallbackSig = Callable[..., _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.

AsyncSelfInjecting #

Bases: ABC, Generic[_CallbackT]

Deprecated interface of a class for marking async functions as self-injecting.

deprecated

This is deprecated as of v0.2.0, use Client.auto_inject_async.

callback abstractmethod property #

callback

The callback this wraps.

__call__ abstractmethod async #

__call__(*args: typing.Any, **kwargs: typing.Any) -> _T

__call__(*args: typing.Any, **kwargs: typing.Any) -> _T

__call__(*args, **kwargs)

Call this with the provided arguments and any injected arguments.

Parameters:

  • *args (Any, default: () ) –

    Positional arguments to pass to the callback.

  • **kwargs (Any, default: {} ) –

    Keyword arguments to pass to the callback alongside injected arguments.

Returns:

  • _T –

    The callback's result.

Raises:

  • MissingDependencyError –

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

Client #

Bases: ABC

Abstract interface of a dependency injection client.

as_async_self_injecting abstractmethod #

as_async_self_injecting(callback)

Deprecated callback for making async functions auto-inject.

deprecated

This is deprecated as of v0.2.0, use Client.auto_inject_async.

as_self_injecting abstractmethod #

as_self_injecting(callback)

Deprecated callback for making functions auto-inject.

deprecated

This is deprecated as of v0.2.0, use Client.auto_inject.

auto_inject #

auto_inject(callback)

Wrap a function to make calls to it always inject dependencies.

Examples:

@client.auto_inject
def callback(dep: Injected[Type]) -> None:
    ...

callback()  # The requested dependencies will be passed.

Parameters:

  • callback (Callable[_P, _T]) –

    The callback to wrap with DI.

Returns:

  • Callable –

    The wrapped auto injecting callback.

auto_inject_async #

auto_inject_async(callback)

Wrap an async function to make calls to it always inject dependencies.

Examples:

@client.auto_inject_async
async def callback(dep: Injected[Type]) -> None:
    ...

await callback()  # The requested dependencies will be passed.

Parameters:

  • callback (Callable[_P, _CoroT[_T]]) –

    The callback to wrap with DI.

Returns:

  • Callable –

    The wrapped auto injecting callback.

call_with_async_di 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 (Any, default: () ) –

    Positional arguments to pass to the callback.

  • **kwargs (Any, default: {} ) –

    Keyword arguments to pass to the callback.

Returns:

  • _T –

    The result of the callback.

Raises:

  • MissingDependencyError –

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

  • SyncOnlyError –

    If the callback or any of its callback dependencies are async.

call_with_ctx abstractmethod #

call_with_ctx(ctx: Context, callback: collections.Callable[..., _CoroT[typing.Any]], /, *args: typing.Any, **kwargs: typing.Any) -> typing.NoReturn

call_with_ctx(ctx: Context, callback: collections.Callable[..., _T], /, *args: typing.Any, **kwargs: typing.Any) -> _T

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 (Callable[..., _T]) –

    The callback to call.

    This must be sync.

  • *args (Any, default: () ) –

    Positional arguments to pass to the callback.

  • **kwargs (Any, default: {} ) –

    Keyword arguments to pass to the callback.

Returns:

  • _T –

    The result of the callback.

Raises:

  • MissingDependencyError –

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

  • 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 (Any, default: () ) –

    Positional arguments to pass to the callback.

  • **kwargs (Any, default: {} ) –

    Keyword arguments to pass to the callback.

Returns:

  • _T –

    The result of the callback.

Raises:

  • MissingDependencyError –

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

call_with_di #

call_with_di(callback: collections.Callable[..., _CoroT[typing.Any]], /, *args: typing.Any, **kwargs: typing.Any) -> typing.NoReturn

call_with_di(callback: collections.Callable[..., _T], /, *args: typing.Any, **kwargs: typing.Any) -> _T

call_with_di(callback, /, *args, **kwargs)

Call a function with sync dependency injection.

Parameters:

  • callback (Callable[..., _T]) –

    The callback to call.

    This must be sync.

  • *args (Any, default: () ) –

    Positional arguments to pass to the callback.

  • **kwargs (Any, default: {} ) –

    Keyword arguments to pass to the callback.

Returns:

  • _T –

    The result of the callback.

Raises:

  • MissingDependencyError –

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

  • 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:

get_type_dependency abstractmethod #

get_type_dependency(type_: type[_T]) -> _T

get_type_dependency(type_: type[_T], /, *, default: _DefaultT) -> _T | _DefaultT

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

Get the implementation for an injected type.

Parameters:

  • type_ (type[_T]) –

    The associated type.

  • default (_DefaultT, default: ... ) –

    The default value to return if the type is not implemented.

Returns:

  • _T | _DefaultT –

    The resolved type if found.

    If the type isn't implemented then the value of default will be returned if it is provided.

Raises:

  • KeyError –

    If no dependency was found when no default was provided.

make_context abstractmethod #

make_context()

Create a dependency injection context.

Returns:

  • Context –

    The created DI context, bound to the current client.

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_)

Remove a type dependency.

Parameters:

  • type_ (type[Any]) –

    The associated type.

Returns:

  • Self –

    The client instance to allow chaining.

Raises:

  • KeyError –

    If type is not registered.

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 the value for a type dependency.

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 #

Bases: ABC

Abstract interface of an injection context.

injection_client abstractmethod property #

injection_client

Injection client this context is bound to.

cache_result #

cache_result(callback, value)

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

Whether this does anything or is a noop is implementation detail.

Parameters:

  • callback (CallbackSig[_T]) –

    The callback to cache the result of.

  • value (_T) –

    The value to cache.

call_with_async_di 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 (Any, default: () ) –

    Positional arguments to pass to the callback.

  • **kwargs (Any, default: {} ) –

    Keyword arguments to pass to the callback.

Returns:

  • _T –

    The result of the callback.

Raises:

  • MissingDependencyError –

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

call_with_di #

call_with_di(callback: collections.Callable[..., _CoroT[typing.Any]], /, *args: typing.Any, **kwargs: typing.Any) -> typing.NoReturn

call_with_di(callback: collections.Callable[..., _T], /, *args: typing.Any, **kwargs: typing.Any) -> _T

call_with_di(callback, /, *args, **kwargs)

Call a function with the current DI context.

Parameters:

  • callback (Callable[..., _T]) –

    The callback to call.

    This must be sync.

  • *args (Any, default: () ) –

    Positional arguments to pass to the callback.

  • **kwargs (Any, default: {} ) –

    Keyword arguments to pass to the callback.

Returns:

  • _T –

    The result of the callback.

Raises:

  • MissingDependencyError –

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

  • SyncOnlyError –

    If the callback or any of its callback dependencies are async.

get_cached_result #

get_cached_result(callback: CallbackSig[_T]) -> _T

get_cached_result(callback: CallbackSig[_T], /, *, default: _DefaultT) -> _T | _DefaultT

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

Get the cached result of a callback.

This will always raise/default for context implementations with no caching.

Parameters:

  • callback (CallbackSig[_T]) –

    The callback to get the cached result of.

  • default (_DefaultT | _NoValue, default: _NO_VALUE ) –

    The default value to return if the callback is not cached.

Returns:

  • _T | _DefaultT –

    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.

Raises:

  • KeyError –

    If no value was found when no default was provided.

get_type_dependency abstractmethod #

get_type_dependency(type_: type[_T]) -> _T

get_type_dependency(type_: type[_T], /, *, default: _DefaultT) -> _T | _DefaultT

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

Get the implementation for an injected type.

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

Parameters:

  • type_ (type[_T]) –

    The associated type.

  • default (_DefaultT, default: ... ) –

    The default value to return if the type is not implemented.

Returns:

  • _T | _DefaultT –

    The resolved type if found.

    If the type isn't implemented then the value of default will be returned if it is provided.

Raises:

  • KeyError –

    If no dependency was found when no default was provided.

SelfInjecting #

Bases: ABC, Generic[_SyncCallbackT]

Deprecated interface of a class for marking functions as self-injecting.

deprecated

This is deprecated as of v0.2.0, use Client.auto_inject.

callback abstractmethod property #

callback

The callback this wraps.

__call__ abstractmethod #

__call__(*args, **kwargs)

Call this callback with the provided arguments + injected arguments.

Parameters:

  • *args (Any, default: () ) –

    Positional arguments to pass to the callback.

  • **kwargs (Any, default: {} ) –

    Keyword arguments to pass to the callback.

Returns:

  • _T –

    The callback's result.

Raises:

  • MissingDependencyError –

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

  • SyncOnlyError –

    If the callback or any of its callback dependencies are async.