API Reference¶

Container¶

The core dependency injection container.

from dijay import Container

Container()¶

Creates an empty container with no registered providers.

Container.from_module(mod) -> Container¶

Creates a container from a module hierarchy. Scans the module tree, registers all providers, and returns a fully configured Container.

container = Container.from_module(AppModule)

container.injectable(token=None, scope=SINGLETON)¶

Decorator that registers a class or factory as a provider.

@container.injectable(scope=TRANSIENT)
class EmailSender: ...

container.register(token, provider, scope=SINGLETON)¶

Explicitly bind a provider to a token at runtime.

container.register(Database, FakeDatabase)

container.resolve(token, id=None) -> T¶

Resolve a dependency by token, respecting its scope.

Raises RuntimeError on circular dependency or unregistered token.

service = await container.resolve(MyService)

container.call(target, id=None, **kwargs)¶

Invoke a callable with dependencies resolved and injected automatically.

result = await container.call(my_function)

container.on_bootstrap(fn)¶

Register a hook to run during bootstrap().

container.on_shutdown(fn)¶

Register a hook to run during shutdown().

container.bootstrap()¶

Execute all registered bootstrap hooks in order.

container.shutdown()¶

Execute all shutdown hooks and clear internal caches.

Async Context Manager¶

The container supports async with for automatic lifecycle management:

async with Container.from_module(AppModule) as container:
    # @on_bootstrap hooks ran
    ...
# @on_shutdown hooks ran

Module-Level Shortcuts¶

These are shortcuts that operate on a global Container instance. Ideal for simple apps:

from dijay import injectable, register, resolve, instance

Provide¶

Dataclass for custom provider registration within modules.

from dijay import Provide

@module(providers=[
    Provide("DB_URL", use_value="postgresql://localhost/mydb"),
    Provide(Cache, use_class=RedisCache),
    Provide(HttpClient, use_factory=create_http_client),
])
class InfraModule: ...

Inject¶

Marker used in Annotated type hints to specify a custom injection token.

from dijay import Inject

def __init__(self, url: Annotated[str, Inject("DB_URL")]): ...

module¶

Decorator that marks a class as a Module, and namespace for lifecycle decorators.

from dijay import module

As a decorator¶

Marks a class as a Module, grouping providers and configuring imports/exports.

@module(providers=[Database], imports=[ConfigModule])
class AppModule: ...

module.on_bootstrap(fn=None, /, container=None)¶

Decorator to register a bootstrap hook. If container is omitted, registers on the global container.

# On a method (uses the container that resolves the class)
@module.on_bootstrap
async def connect(self): ...

# On a standalone function with specific container
@module.on_bootstrap(container=c)
async def startup(db: Database): ...

module.on_shutdown(fn=None, /, container=None)¶

Decorator to register a shutdown hook. If container is omitted, registers on the global container.

@module.on_shutdown
async def disconnect(self): ...

@module.on_shutdown(container=c)
async def teardown(): ...

DynamicModule¶

TypedDict returned by static methods to configure dynamic modules.

from dijay import DynamicModule

Scope Constants¶

from dijay import SINGLETON, TRANSIENT, REQUEST