Skip to content

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.