Container

FastDI Container and execution utilities.

This module wraps the PyO3 Rust core with a maintainable, typed Python API. It provides scopes, overrides, observability hooks, async resolution, and topological plan compilation for async execution.

Container

User-facing DI container.

Provides registration, overrides, scopes, hooks, and resolution helpers. The heavy lifting (caching, provider invocation, overrides storage) happens in the Rust core. This Python wrapper adds ergonomics and async tooling.

add_hook(hook)

Register an observability hook.

The hook is called as hook(event: str, payload: dict) for events like provider_start, provider_end, and cache_hit.

override(key_or_callable, replacement, *, singleton=False)

Temporarily override a provider within the context block.

Parameters:

Name	Type	Description	Default
key_or_callable	Any	Provider key or original callable.	required
replacement	Callable[..., Any]	Replacement provider (sync or async).	required
singleton	bool	Treat replacement as a singleton in Rust cache.	False

register(key, func, *, singleton, dep_keys=None, scope=None)

Register a provider function under a given key.

Parameters:

Name	Type	Description	Default
key	Key	Unique provider identifier.	required
func	Callable[..., Any]	Provider callable (sync or async).	required
singleton	bool	Cache result globally in Rust if True.	required
dep_keys	list[Key] | None	Optional explicit dependency keys; inferred from Annotated parameter metadata otherwise.	None
scope	Scope | None	Python-side scope: "transient", "request", or "singleton".	None

remove_hook(hook)

Unregister a previously added hook.

It is safe to call even if the hook is not currently registered.

resolve(key)

Resolve a single key synchronously via the Rust core.

Raises:

Type	Description
KeyError	If no provider is registered for the key.
RuntimeError	On dependency cycles or invalid graph for sync.

resolve_async(key) async

Resolve a single key in async mode.

This path supports async providers, request scope, and hooks.

resolve_many(keys)

Resolve multiple keys synchronously via the Rust core.

resolve_many_async(keys) async

Resolve multiple keys in async mode.