Types

Lifetime

class diwire.Lifetime(*values)

Define cache behavior for provider results.

SCOPED = 2

Cache per declared scope owner until that scope exits.

For registrations declared on the container root scope, this behaves like a singleton for the container lifetime. Cleanup-enabled providers are released when the owning scope/resolver is closed.

TRANSIENT = 1

Disable caching and build a new value for every resolution call.

LockMode

class diwire.LockMode(*values)

Select locking behavior for cached provider resolution.

Use these values for provider-level lock_mode or container-level defaults. Container methods also accept "auto" at configuration time: DIWire maps "auto" to async locks when a graph requires async resolution and to thread locks for sync-only graphs.

In mixed workloads, prefer forcing THREAD for high-throughput sync cached paths when you do not want auto mode to pick async locks.

ASYNC = 'async'

Guard cached values with asyncio.Lock for async resolution paths.

NONE = 'none'

Disable locking around cache reads/writes for this provider.

THREAD = 'thread'

Guard cached values with threading.Lock in synchronous paths.

ResolverProtocol

class diwire.ResolverProtocol(*args, **kwargs)

Protocol for a dependency resolver.

async aclose(exc_type=None, exc_value=None, traceback=None)

Asynchronously close the resolver by forwarding to __aexit__.

Parameters:

• exc_type – Exception type forwarded to close hooks.

• exc_value – Exception instance forwarded to close hooks.

• traceback – Traceback forwarded to close hooks.

async aresolve(dependency)

Resolve the given dependency asynchronously and return its instance.

Parameters:

dependency – Dependency key to resolve.

close(exc_type=None, exc_value=None, traceback=None)

Close the resolver by forwarding to __exit__ with the given exception context.

Parameters:

• exc_type – Exception type forwarded to close hooks.

• exc_value – Exception instance forwarded to close hooks.

• traceback – Traceback forwarded to close hooks.

enter_scope(scope=None)

Enter a new scope and return a new resolver for that scope.

Parameters:

scope – Scope value used to filter registrations or open nested resolution scope.

resolve(dependency)

Resolve the given dependency and return its instance.

Parameters:

dependency – Dependency key to resolve.

Scope

class diwire.BaseScope(*args, **_kwargs)

Represent a numeric DI scope level with transition metadata.

A scope behaves like an int so comparisons and ordering are based on level. skippable marks helper scopes that can be skipped by default transitions when enter_scope(None) chooses the next non-skippable scope.

diwire.Scope = Scopes(skippable=(Scope.SESSION(2, skippable=True),), APP=Scope.APP(1, skippable=False), SESSION=Scope.SESSION(2, skippable=True), REQUEST=Scope.REQUEST(3, skippable=False), ACTION=Scope.ACTION(4, skippable=False), STEP=Scope.STEP(5, skippable=False))

Define the built-in DI scope ladder ordered by level.

Levels increase with nesting depth. Calling enter_scope() with no explicit target transitions to the next deeper non-skippable scope.

Examples

with container.enter_scope(Scope.REQUEST) as request_resolver:
    service = request_resolver.resolve(Service)

Injected

class diwire.Injected

Mark a parameter for container-driven injection.

At runtime Injected[T] resolves to Annotated[T, InjectedMarker()].

Examples

@resolver_context.inject
def run(service: Injected[Service], value: int) -> str:
    return service.handle(value)

Component

class diwire.Component(value)

Differentiate multiple providers for the same base type.

Attach Component metadata to typing.Annotated so DIWire treats each annotated key as distinct at runtime.

Examples

from typing import Annotated, TypeAlias


class Database: ...


ReplicaDb: TypeAlias = Annotated[Database, Component("replica")]
PrimaryDb: TypeAlias = Annotated[Database, Component("primary")]

All

class diwire.All

Resolve all implementations registered for a base dependency key.

At runtime All[T] resolves to Annotated[T, AllMarker(dependency_key=T)] and is detected by the resolver dispatch to collect the plain registration for T (if any) plus all component-qualified registrations keyed as Annotated[T, Component(...)].

Notes

If you pass an Annotated[...] token (for example All[Annotated[T, Component('x')]]), DIWire strips it to the base type T and produces the same token as All[T]. Prefer using All[BaseType].

Maybe

class diwire.Maybe

Mark a dependency as explicitly optional.

At runtime Maybe[T] resolves to Annotated[T, MaybeMarker()].

Provider

class diwire.Provider

Mark a dependency for lazy resolver-bound sync provider injection.

AsyncProvider

class diwire.AsyncProvider

Mark a dependency for lazy resolver-bound async provider injection.