waku [枠] means framework in Japanese.
waku is a Python framework for building modular, loosely coupled, and maintainable applications.
It draws inspiration from NestJS and Tramvai,
adapting their best ideas to the Python ecosystem. Here's list of some waku key features:
- 🧩 Modularity: Build applications as a set of loosely coupled modules
- 💉 Powerful Dependency Injection System: Manage dependencies with built-in DI framework-agnostic IoC-container
- 🔧 Extensions: Use application and modules lifecycle hooks to
extend
waku - 📊 Lifespan: Automatic manage application and IoC-container lifecycle
- ⚙️ Command/Query handling (CQRS): Use mediator abstraction heavily inspired by C# MediatR library to handle commands and queries
- 🤝 Integrations:
wakucomes with built-in integrations for popular web frameworks like FastAPI or Litestar and allows you to easily create your own integrations with any other frameworks
- Build modular monoliths with clear boundaries
- Enforce loose coupling between components
- Automatically validate dependency graphs
- Control module visibility and access
- Built-in extension mechanism
- Lifecycle hooks for modules and applications
- Custom extension points
- Rich ecosystem of built-in extensions (work in progress)
- Framework-agnostic DI implementation
- Providers with different lifetimes (singleton, scoped, transient, object)
- Simplified testing and mocking
waku includes a built-in CQRS implementation with all the features you need to build robust,
maintainable applications:
- Command and Query request handling
- Event handling with custom publishers support
- Middleware support
Install the waku package using your preferred tool.
We recommend uv for managing project dependencies due to its speed and simplicity.
# Using UV
uv add waku
# Using pip
pip install waku
# Using poetry
poetry add wakuYou also need to install some additional dependencies for the DI system to work.
You can explore all available providers in our documentation.
For our example we stick with aioinject as DI provider.
Install it directly using your preferred package manager or as extra dependency of waku:
uv add "waku[aioinject]"import asyncio
from waku import ApplicationFactory, module
from waku.di import Scoped, Injected, inject
from waku.di.contrib.aioinject import AioinjectDependencyProvider
# Define your providers
class GreetingService:
async def greet(self, name: str) -> str:
return f'Hello, {name}!'
# Define a module with your providers
@module(providers=[Scoped(GreetingService)])
class GreetingModule:
pass
# Define the application composition root module
@module(imports=[GreetingModule])
class AppModule:
pass
# Define entrypoints
# In a real-world scenario, this could be FastAPI routes, etc.
@inject
async def greet_user(greeting_service: Injected[GreetingService]) -> str:
return greeting_service.greet('waku')
async def main() -> None:
# Create application via factory
application = ApplicationFactory.create(
AppModule,
dependency_provider=AioinjectDependencyProvider(),
)
# Run the application
# In a real-world scenario, this would be run by a framework like FastAPI
async with application, application.container.context():
message = await greet_user()
print(message) # Output: Hello, waku!
if __name__ == '__main__':
asyncio.run(main())For explanations of the code above and more realistic examples, see the Getting Started guide.
Explore detailed documentation on our official site.
Key topics include:
We’d love your contributions! Check out our Contributing Guide to get started.
Learn how to set up a development environment in the Contributing Guide.