Modules¶

In a typical Python project, any file can import from any other file. This works fine at first, but as the codebase grows, hidden dependencies pile up: services reach into each other's internals, circular imports appear, and nobody can tell what depends on what without reading every file.

Modules solve this by giving your code explicit boundaries. Each module declares what it provides (providers), what it needs from other modules (imports), and what it exposes to the outside (exports). Everything else stays private. waku enforces these boundaries at startup — if a module tries to use something it didn't import, you get an error, not a silent bug.

graph LR
    subgraph ModuleA
        direction TB
        SA[ServiceA]
    end

    subgraph ModuleB
        direction TB
        SB[ServiceB]
    end

    subgraph AppModule [AppModule · root]
        direction TB
    end

    AppModule -->|imports| ModuleA
    AppModule -->|imports| ModuleB
    ModuleB -->|imports| ModuleA
    ModuleA -.->|exports ServiceA| ModuleB

Module¶

A module is a class annotated with the @module() decorator. This decorator attaches metadata to the class, which waku uses to construct the application graph.

Group related code into a module — a users module holds the user service and repository, an orders module holds order processing logic. Each module is a self-contained unit with a clear responsibility, making the codebase easier to navigate and reason about as it grows.

Every waku application has at least one module: the root module, also known as the composition root. This module serves as the starting point for WakuFactory to build the entire application graph.

Modules encapsulate providers by default — you can only inject providers that are part of the current module or explicitly exported from imported modules. This is the key difference from plain Python imports: if you forget to export a provider, other modules simply can't use it. The exported providers serve as the module's public API.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

from waku import module
from waku.di import scoped

from app.modules.config.module import ConfigModule


class UsersService:
    pass


@module(
    providers=[scoped(UsersService)],  # Register the service with a scoped lifetime
    imports=[ConfigModule],  # Import another module
    exports=[UsersService],  # Expose the service to other modules
)
class UsersModule:
    pass


@module(imports=[UsersModule])  # Root module importing UsersModule
class AppModule:
    pass

Module Re-exporting¶

Sometimes you want to group several modules behind a single facade. Re-exporting lets a module expose another module's providers to its own consumers — without duplicating any registrations.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

from waku import module

from app.modules.users.module import UsersModule


@module(
    imports=[UsersModule],
    exports=[UsersModule],
)
class IAMModule:
    pass

graph LR
    subgraph UsersModule
        US[UserService]
    end

    subgraph IAMModule [IAMModule · facade]
        direction TB
    end

    subgraph FeatureModule
        direction TB
    end

    IAMModule -->|imports| UsersModule
    IAMModule -.->|re-exports| UsersModule
    FeatureModule -->|imports| IAMModule
    UsersModule -.->|UserService| FeatureModule

Global Modules¶

Some providers are needed everywhere — database connections, configuration, logging. Adding imports=[InfraModule] to every feature module is tedious and adds noise without adding information. For these cases, you can mark a module as global.

A global module's exported providers become available to every module in the application without explicit imports. Set is_global=True in the @module() decorator and register the module once in the root module:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

from waku import module
from waku.di import scoped, singleton

from app.db import AsyncEngine, AsyncSession


@module(
    providers=[
        singleton(AsyncEngine),
        scoped(AsyncSession),
    ],
    exports=[AsyncEngine, AsyncSession],
)
class DatabaseModule:
    pass


@module(
    imports=[DatabaseModule],
    exports=[DatabaseModule],
    is_global=True,
)
class InfraModule:
    pass

graph LR
    subgraph InfraModule ["InfraModule · global"]
        direction TB
        DB[DatabaseModule]
    end

    subgraph AppModule [AppModule · root]
        direction TB
    end

    subgraph UsersModule
        direction TB
        US[UserService]
    end

    subgraph OrdersModule
        direction TB
        OS[OrderService]
    end

    AppModule -->|imports| InfraModule
    AppModule -->|imports| UsersModule
    AppModule -->|imports| OrdersModule
    InfraModule -.->|"AsyncSession (available everywhere)"| UsersModule
    InfraModule -.->|"AsyncSession (available everywhere)"| OrdersModule

With InfraModule imported in the root module, any feature module can inject AsyncSession without adding DatabaseModule to its own imports.

Dynamic Module¶

Sometimes a module can't build its providers on its own — it needs a value from the outside: an environment name, a connection string, a list of entities to register. Dynamic modules solve this by accepting parameters at import time and turning them into providers internally.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

from dataclasses import dataclass
from typing import Literal

from waku import DynamicModule, module
from waku.di import object_

Environment = Literal['dev', 'prod']


@dataclass(kw_only=True)
class AppSettings:
    environment: Environment
    debug: bool


@module(is_global=True)
class ConfigModule:
    @classmethod
    def register(cls, env: Environment) -> DynamicModule:
        settings = AppSettings(environment=env, debug=env == 'dev')
        return DynamicModule(
            parent_module=cls,
            providers=[object_(settings)],
        )

graph LR
    ENV["env='dev'"] -->|parameter| REG["ConfigModule.register()"]
    REG -->|creates| DM[DynamicModule]
    DM -->|provides| AS[AppSettings]

Then import the dynamic module by calling its register() method:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

from waku import module

from app.modules.config.module import ConfigModule


@module(
    imports=[ConfigModule.register(env='dev')],
)
class AppModule:
    pass

You can also make a dynamic module global by setting is_global=True in the DynamicModule constructor.

Further reading¶

• Providers — provider types and scopes for dependency injection
• Lifecycle Hooks — module and application extension hooks
• Custom Extensions — writing your own module extensions
• Validation — encapsulation rules and how to configure them