Metadata-Version: 2.4
Name: causeway
Version: 0.3.1
Summary: A lean backend framework for type-safe Python APIs — file-based routing, typed config/DI, scoped providers, plugin registry, and background tasks.
Project-URL: Homepage, https://github.com/tamimbinhakim/causeway
Project-URL: Documentation, https://github.com/tamimbinhakim/causeway/tree/main/docs
Project-URL: Repository, https://github.com/tamimbinhakim/causeway
Project-URL: Issues, https://github.com/tamimbinhakim/causeway/issues
Project-URL: Changelog, https://github.com/tamimbinhakim/causeway/blob/main/packages/causeway/CHANGELOG.md
Author-email: Tamim Bin Hakim <tamimbinhakim.work@gmail.com>
License: MIT
Keywords: asgi,backend-framework,background-tasks,dependency-injection,dyadpy,file-based-routing
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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 :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: anyio>=4.13.0
Requires-Dist: dyadpy>=0.1.1
Requires-Dist: msgspec>=0.19
Requires-Dist: pydantic-settings>=2.14.1
Requires-Dist: pydantic>=2.13.4
Requires-Dist: rich>=15.0.0
Requires-Dist: starlette>=1.0.0
Requires-Dist: structlog>=25.5.0
Requires-Dist: typer>=0.25.1
Requires-Dist: uvicorn[standard]>=0.47.0
Requires-Dist: watchfiles>=1.1.1
Provides-Extra: all
Requires-Dist: dramatiq[redis]>=2.1.0; extra == 'all'
Requires-Dist: nuitka>=2.5; extra == 'all'
Requires-Dist: opentelemetry-api>=1.41.1; extra == 'all'
Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.41.1; extra == 'all'
Requires-Dist: opentelemetry-instrumentation-asgi>=0.62b1; extra == 'all'
Requires-Dist: opentelemetry-sdk>=1.41.1; extra == 'all'
Provides-Extra: binary
Requires-Dist: nuitka>=2.5; extra == 'binary'
Provides-Extra: dramatiq
Requires-Dist: dramatiq[redis]>=2.1.0; extra == 'dramatiq'
Provides-Extra: otel
Requires-Dist: opentelemetry-api>=1.41.1; extra == 'otel'
Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.41.1; extra == 'otel'
Requires-Dist: opentelemetry-instrumentation-asgi>=0.62b1; extra == 'otel'
Requires-Dist: opentelemetry-sdk>=1.41.1; extra == 'otel'
Description-Content-Type: text/markdown

# causeway (Python)

> A lean backend framework for type-safe Python APIs.

```bash
uv add 'causeway==0.1.0a0'   # alpha — drop the pin once v0.1.0 ships
```

This is the core Python package of [Causeway](https://github.com/tamimbinhakim/causeway). It ships:

- A **file-based router** that walks `src/app/routes/**/*.py`, picks up `[id].py`, `(group)/`, `_middleware.py`, and `_scope.py`, and registers handlers into the app's route table.
- A **typed config layer** that wraps `pydantic-settings` and exposes non-secret fields to the generated TypeScript client.
- A **scoped DI container** driven by `_scope.py` providers.
- A **`@task` contract** for background jobs with a Dramatiq reference adapter.
- A **plugin registry** with Python-entry-point discovery and per-environment activation.
- A **CLI** (`causeway new`, `causeway dev`, `causeway build`, `causeway deploy <target>`) that runs the whole loop.

For the full story, the design rationale, and a side-by-side vs. FastAPI / Django + Ninja / Encore.ts / NestJS, see the [repo README](https://github.com/tamimbinhakim/causeway).

## 30-second example

```
my-app/
├── pyproject.toml
├── causeway.toml
└── src/app/
    ├── config.py
    ├── plugins.py
    └── routes/
        ├── _middleware.py
        ├── index.py
        └── users/
            ├── _scope.py
            ├── index.py
            └── [id].py
```

```python
# src/app/routes/users/[id].py
from typing import Annotated
from uuid import UUID
from msgspec import Struct
from causeway import get, raises
from causeway.errors import NotFound

class User(Struct):
    id: UUID
    name: str

@get
@raises(NotFound)
async def show(id: UUID) -> User:
    ...
```

Run it:

```bash
causeway dev
```

`causeway dev` discovers the routes, boots uvicorn, regenerates a typed `client.ts` for your frontend on every save, and exposes `/__causeway` with the route tree, registered tasks, current config, and plugin list.

## Primitives in this package

| Primitive                                        | Purpose                                                                  |
| ------------------------------------------------ | ------------------------------------------------------------------------ |
| File router (`[id].py`, `(group)/`)              | Discovery + URL pattern generation.                                      |
| `_middleware.py` / `_scope.py`                   | Per-subtree middleware + scoped DI providers.                            |
| `Settings` (wraps `pydantic-settings`)           | Typed config with allowlisted exposure to the generated client.          |
| `@get` / `@post` / `@put` / `@patch` / `@delete` | HTTP method decorators.                                                  |
| `@task(...)`                                     | Background-job contract; adapter-agnostic.                               |
| `@cron(...)`                                     | Scheduled tasks via the same adapter.                                    |
| `register(...)`                                  | Plugin registration (`TaskAdapter`, `Storage`, `KV`, `AuthProvider`, …). |
| `TestApp`                                        | Test client with DI overrides and `tasks_eager()` mode.                  |
| `causeway` CLI                                       | `new`, `dev`, `build`, `plugins`, `deploy <target>`.                     |

Full reference: <https://github.com/tamimbinhakim/causeway/tree/main/docs/api-reference>

## Optional extras

```bash
uv add 'causeway[dramatiq]'  # reference task adapter
uv add 'causeway[otel]'      # OpenTelemetry middleware hooks
uv add 'causeway[all]'       # everything
```

## Scope

Causeway ships project shape and a small set of contracts. It does **not** ship vertical integrations — no ORM, no admin panel, no template engine, no infrastructure provisioning. Those layers compose on top of the fundamentals and live in their own plugin packages or in user code.

## License

MIT
