Skip to content

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

callback abstractmethod property #

callback: _CallbackT

The callback this wraps.

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

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.

Parameters:

  • callback (CallbackSig) –

    The callback to make self-injecting.

    This may be sync or async.

Returns:

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:

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:

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:

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:

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:

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_, /, *, 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_)

Remove a type dependency.

Parameters:

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 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 #

Bases: abc.ABC

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:

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:

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

callback abstractmethod property #

callback: _SyncCallbackT

The callback this wraps.

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

Undefined #

Deprecated type of the UNDEFINED constant.

deprecated

This will be removed in v0.2.0.