Skip to content

alluka.local#

Standard functions for using a local scope dependency injection client.

The "scope" will either be the current thread, an asynchronous runtime or an asynchronous event/task.

Note

This module's functionality will only work if scope_client or scope_context has been called to set the DI context for the local scope.

initialise module-attribute #

initialise = initialize

Alias of initialize.

auto_inject #

auto_inject(callback)

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

Examples:

@alluka.local.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:

@alluka.local.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: collections.Callable[..., collections.Coroutine[typing.Any, typing.Any, _T]], *args: typing.Any, **kwargs: typing.Any) -> _T

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

call_with_async_di(callback, *args, **kwargs)

Use the local context/client to call a callback with async DI.

Parameters:

  • callback (CallbackSig[_T]) –

    The callback to call.

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

    Positional arguments to passthrough to the callback.

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

    Keyword arguments to passthrough to the callback.

Returns:

  • _T –

    The result of the call.

call_with_di #

call_with_di(callback, *args, **kwargs)

Use the local context/client to call a callback with DI.

Parameters:

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

    The callback to call.

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

    Positional arguments to passthrough to the callback.

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

    Keyword arguments to passthrough to the callback.

Returns:

  • _T –

    The result of the call.

get #

get() -> abc.Client

get(*, default: _DefaultT) -> abc.Client | _DefaultT

get(*, default=_NO_VALUE)

Deprecated alias of get_client.

get_client #

get_client() -> abc.Client

get_client(*, default: _DefaultT) -> abc.Client | _DefaultT

get_client(*, default=_NO_VALUE)

Get the local client for the current scope.

Parameters:

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

    The value to return if no client is set for the current scope.

    If not provided, a RuntimeError will be raised instead.

Returns:

  • Client | _DefaultT –

    The client for the local scope, or the default value if no client is set for the current scope.

Raises:

  • RuntimeError –

    If no client is present in the current scope and no default value was provided.

get_context #

get_context(*, from_client: bool = True) -> abc.Context

get_context(*, default: _DefaultT, from_client: bool = True) -> abc.Context | _DefaultT

get_context(*, default=_NO_VALUE, from_client=True)

Get the local context for the current scope.

Parameters:

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

    The value to return if no context is set for the current scope.

    If not provided, a RuntimeError will be raised instead.

  • from_client (bool, default: True ) –

    Whether to try to make a context from the in-scope Alluka client when no context is set for the current scope.

Returns:

  • Context | _DefaultT –

    The context for the local scope, or the default value if no context is set for the current context.

Raises:

  • RuntimeError –

    If the context is not set for the current context and no default value was provided.

initialize #

initialize(client=None)

Link or initialise an injection client for the current scope.

This uses contextvars to store the client and therefore will not be inherited by child threads.

scope_client and scope_context are recommended over this.

Parameters:

  • client (Client | None, default: None ) –

    If provided, this will be set as the client for the current scope. If not provided, a new client will be created.

Returns:

  • Client –

    The created alluka client.

Raises:

  • RuntimeError –

    If the local client is already set for the current scope.

scope_client #

scope_client(client=None)

Set the Alluka client for the scope within a context manager.

This uses contextvars to store the client and therefore will not be inherited by child threads.

Note

The client attached to a context set with scope_context will take priority.

Examples:

def uses_di() -> None:
    alluka.local.call_with_di(other_callback)

with alluka.local.scope_client() as client:
    client.set_type_dependency(Type, value)
    uses_di()

client = alluka.Client()
client.set_type_dependency(Type, value)

with alluka.local.scope_client(client):
    uses_local_di()

Parameters:

  • client (Client | None, default: None ) –

    The client to set for the context manager's scope.

    If not provided then a new client will be created.

Returns:

scope_context #

scope_context(context=None)

Set the Alluka context for the scope within a context manager.

This uses contextvars to store the context and therefore will not be inherited by child threads.

Examples:

context = (
    alluka.OverridingContext(alluka.local.get_context())
    .set_type_dependency(TypeA, value_a)
)

with alluka.local.scope_context(context):
    uses_local_di()

Parameters:

  • context (Context | None, default: None ) –

    The context to set for the context manager's scope.

    If not provided then the in-scope Alluka client is used to generate a new context.

Returns:

Raises:

  • RuntimeError –

    When context isn't provided and no Alluka client has been set for the current scope.