Metadata-Version: 2.4
Name: waku
Version: 0.3.0
Summary: Microframework for building modular and loosely coupled applications
Project-URL: Changelog, https://github.com/waku-py/waku/blob/master/CHANGELOG.md
Project-URL: Issues, https://github.com/waku-py/waku/issues
Project-URL: Repository, https://github.com/waku-py/waku
Author-email: Daniil Kharkov <fadeddexofan@gmail.com>, Doctor <thirvondukr@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: architecture,decoupled,framework,modular
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: typing-extensions>=4.12.0
Provides-Extra: aioinject
Requires-Dist: aioinject>=0.36.1; extra == 'aioinject'
Provides-Extra: litestar
Requires-Dist: litestar>2; extra == 'litestar'
Description-Content-Type: text/markdown

# waku

<p align="left">
    <sup><i>waku</i> [<b>枠</b>] <i>means framework in Japanese.</i></sup>
    <br/>
</p>

<div align="center">

[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
[![Python version](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff/)
[![Checked with mypy](http://www.mypy-lang.org/static/mypy_badge.svg)](http://mypy-lang.org/)

[![PyPI](https://img.shields.io/pypi/v/waku.svg)](https://pypi.python.org/pypi/waku)
[![Downloads](https://static.pepy.tech/badge/waku/month)](https://pepy.tech/projects/waku)
[![License](https://img.shields.io/pypi/l/waku.svg)](https://github.com/waku-py/waku/blob/master/LICENSE)

</div>

`waku` *is a microframework for building modular and loosely coupled applications.*

This project is heavily inspired by [NestJS](https://github.com/nestjs/nest) & [Tramvai](https://tramvai.dev) frameworks.

## Overview

`waku` helps you build maintainable Python applications by providing:
- Clean architecture patterns
- Dependency injection
- Module system
- Extension system
- Command/Query handling (CQRS)

## Features

### 🏗️ Modular Architecture
- Build modular monoliths with clear boundaries
- Enforce loose coupling between components
- Validate dependency graphs automatically
- Control module visibility and access

### 🔌 Extensible Plugin System
- Built-in extension mechanism
- Lifecycle hooks for modules and applications
- Custom extension points
- Rich ecosystem of built-in extensions

### 💉 Flexible Dependency Injection
- Framework-agnostic DI implementation
- Providers with different lifetimes (singleton, scoped, transient)
- Easy testing and mocking

### 🎮 Command Query Responsibility Segregation (CQRS)
- Built-in CQRS extension
- Command/Query requests handling
- Event handling
- Middleware support

## Quick Start

### Installation

```sh
# Using pip
pip install waku

# Using UV (recommended)
uv add waku

# Using poetry
poetry add waku
```

### Basic Example

```python
import asyncio
from typing import Literal

from waku import Application, ApplicationFactory, DynamicModule, module
from waku.di import Scoped, Injected, inject
from waku.di.contrib.aioinject import AioinjectDependencyProvider


# Define your providers
class UserService:
    async def get_user(self, user_id: str) -> dict[str, str]:
        return {'id': user_id, 'name': 'John Doe'}


# Define a module
@module(providers=[Scoped(UserService)], exports=[UserService])
class UserModule:
    pass


# Dynamic module example
@module()
class ConfigModule:
    @classmethod
    def register(cls, env: Literal['dev', 'prod'] = 'prod') -> DynamicModule:
        # You can select providers based on `env` for example
        if env == 'dev':
            providers = [...]
        else:
            providers = [...]

        return DynamicModule(parent_module=cls, providers=providers)


# Define the application composition root module
@module(
    imports=[
        UserModule,
        ConfigModule.register('dev'),
    ]
)
class AppModule:
    pass


# Create application via factory
async def bootstrap() -> Application:
    return await ApplicationFactory.create(
        AppModule,
        dependency_provider=AioinjectDependencyProvider(),
    )


# Define entrypoints
# In real world this can be FastAPI routes, etc.
@inject
async def handler(user_service: Injected[UserService]) -> dict[str, str]:
    return await user_service.get_user(user_id='123')


# Run the application
# In real world this would be run by a 3rd party framework like FastAPI
async def main() -> None:
    application = await bootstrap()
    async with application, application.container.context():
        result = await handler()
        print(result)


if __name__ == '__main__':
    asyncio.run(main())

```

## Documentation

For detailed documentation, visit our [documentation site](https://waku-py.github.io/waku/).

### Key Topics
- [Getting Started](https://waku-py.github.io/waku/getting-started)
- [Module System](https://waku-py.github.io/waku/modules)
- [Dependency Injection](https://waku-py.github.io/waku/dependency-injection)
- [Extensions](https://waku-py.github.io/waku/extensions)
- [CQRS](https://waku-py.github.io/waku/cqrs)
- [Integrations](https://waku-py.github.io/waku/integrations)

## Contributing

We welcome contributions! Please see our [Contributing Guide](./CONTRIBUTING.md) for details.

### Development Setup

See out contributing guide for [development setup](./CONTRIBUTING.md#development-setup).

## License

This project is licensed under the [MIT License](./LICENSE).
