causeway 0.1.0__tar.gz

causeway-0.1.0/.gitignore

@@ -0,0 +1,93 @@
+# ---- OS ----
+.DS_Store
+Thumbs.db
+desktop.ini
+
+# ---- Editors ----
+.idea/
+*.swp
+*.swo
+*~
+.vscode/*
+!.vscode/settings.json
+!.vscode/extensions.json
+!.vscode/launch.json
+
+# ---- Node ----
+node_modules/
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/sdks
+!.yarn/versions
+.npm/
+.eslintcache
+*.tsbuildinfo
+
+# ---- Build output ----
+dist/
+build/
+out/
+.turbo/
+.cache/
+coverage/
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+# ---- Python ----
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+.python-version-local
+.venv/
+venv/
+env/
+ENV/
+.uv-cache/
+.eggs/
+*.egg-info/
+*.egg
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.nox/
+.hypothesis/
+*.cover
+*.py,cover
+
+# ---- Claude Code harness ----
+.claude/
+!.claude/settings.json
+!.claude/commands/
+
+# ---- Causeway ----
+.causeway/
+
+# ---- Benchmarks ----
+benchmarks/results/
+benchmarks/uv.lock
+
+# ---- Env / secrets ----
+.env
+.env.*
+!.env.example
+*.pem
+*.key
+*.crt
+
+# ---- Misc ----
+*.tgz
+*.zip
+.DS_Store?
+._*

causeway-0.1.0/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog · `causeway`
+
+All notable changes to the `causeway` Python package will be documented in this
+file. Managed automatically by [release-please](https://github.com/googleapis/release-please)
+from [Conventional Commits](https://www.conventionalcommits.org/).
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## 0.1.0 (2026-05-16)
+
+
+### ⚠ BREAKING CHANGES
+
+* drops the 0.1.0a0 pre-release line. The first published versions on PyPI will be 0.1.0.
+* the framework is now distributed as `causeway` (and `causeway-<role>-<impl>` for plugins). Every public surface moves:
+
+### Chores
+
+* prep first 0.1.0 release across all 13 packages ([11ef338](https://github.com/tamimbinhakim/causeway/commit/11ef3382a6263cbe541455dd169a28cf162ebb3d))
+* rename quay → causeway across the repo ([83f1213](https://github.com/tamimbinhakim/causeway/commit/83f1213a2176e8338305f8b30f43379d6a614238))
+
+## [Unreleased]
+
+### Added
+
+- Initial package scaffold: file-based router, typed config / DI,
+  middleware + scope composition, background-task contract + reference
+  adapter, plugin registry, `causeway` CLI.

causeway-0.1.0/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.4
+Name: causeway
+Version: 0.1.0
+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.0a0
+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: 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: 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/blob/main/docs/reference.md>
+
+## 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

causeway-0.1.0/README.md

@@ -0,0 +1,94 @@
+# 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/blob/main/docs/reference.md>
+
+## 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

causeway-0.1.0/pyproject.toml

@@ -0,0 +1,159 @@
+[build-system]
+requires = ["hatchling>=1.29.0"]
+build-backend = "hatchling.build"
+
+[project]
+name = "causeway"
+version = "0.1.0"
+description = "A lean backend framework for type-safe Python APIs — file-based routing, typed config/DI, scoped providers, plugin registry, and background tasks."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.11"
+authors = [{ name = "Tamim Bin Hakim", email = "tamimbinhakim.work@gmail.com" }]
+keywords = [
+  "asgi",
+  "backend-framework",
+  "file-based-routing",
+  "dependency-injection",
+  "background-tasks",
+  "dyadpy",
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Framework :: AsyncIO",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Internet :: WWW/HTTP",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Typing :: Typed",
+]
+
+dependencies = [
+  "dyadpy>=0.1.0a0",
+  "pydantic-settings>=2.14.1",
+  "pydantic>=2.13.4",
+  "msgspec>=0.19",
+  "starlette>=1.0.0",
+  "uvicorn[standard]>=0.47.0",
+  "watchfiles>=1.1.1",
+  "typer>=0.25.1",
+  "rich>=15.0.0",
+  "structlog>=25.5.0",
+  "anyio>=4.13.0",
+]
+
+[project.optional-dependencies]
+dramatiq = ["dramatiq[redis]>=2.1.0"]
+otel = [
+  "opentelemetry-api>=1.41.1",
+  "opentelemetry-sdk>=1.41.1",
+  "opentelemetry-instrumentation-asgi>=0.62b1",
+  "opentelemetry-exporter-otlp-proto-http>=1.41.1",
+]
+all = ["causeway[dramatiq,otel]"]
+
+[project.scripts]
+causeway = "causeway.cli:main"
+
+[project.entry-points."causeway.plugins"]
+# Reference adapters shipped in core register themselves under this group.
+
+[project.urls]
+Homepage = "https://github.com/tamimbinhakim/causeway"
+Documentation = "https://github.com/tamimbinhakim/causeway/tree/main/docs"
+Repository = "https://github.com/tamimbinhakim/causeway"
+Issues = "https://github.com/tamimbinhakim/causeway/issues"
+Changelog = "https://github.com/tamimbinhakim/causeway/blob/main/packages/causeway/CHANGELOG.md"
+
+[dependency-groups]
+dev = [
+  "pytest>=9.0.3",
+  "pytest-asyncio>=1.3.0",
+  "pytest-cov>=7.1.0",
+  "httpx>=0.28.1",
+  "ruff>=0.15.13",
+  "mypy>=2.1.0",
+  "types-setuptools",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/causeway"]
+
+[tool.hatch.build.targets.sdist]
+include = ["/src", "/tests", "/README.md", "/CHANGELOG.md"]
+
+# ---- ruff ----
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = [
+  "E",
+  "F",
+  "W",   # pycodestyle / pyflakes
+  "I",   # isort
+  "B",   # bugbear
+  "UP",  # pyupgrade
+  "SIM", # simplify
+  "C4",  # comprehensions
+  "PT",  # pytest
+  "RUF", # ruff
+  "TID", # tidy imports
+  "PYI", # type stubs
+  "ANN", # annotations
+]
+ignore = [
+  "ANN401", # allow Any in select cases
+  "E501",   # line length handled by formatter
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["ANN", "B017", "PT011", "RUF012"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["causeway"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+docstring-code-format = true
+
+# ---- mypy ----
+[tool.mypy]
+python_version = "3.11"
+strict = true
+warn_unreachable = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+disallow_any_generics = true
+no_implicit_reexport = true
+files = ["src/causeway"]
+
+[[tool.mypy.overrides]]
+module = "tests.*"
+disallow_untyped_defs = false
+
+# ---- pytest ----
+[tool.pytest.ini_options]
+minversion = "8.0"
+testpaths = ["tests"]
+asyncio_mode = "auto"
+addopts = ["-ra", "--strict-markers", "--strict-config"]
+filterwarnings = ["error"]
+
+# ---- coverage ----
+[tool.coverage.run]
+branch = true
+source = ["causeway"]
+omit = ["src/causeway/cli.py"]
+
+[tool.coverage.report]
+exclude_lines = ["pragma: no cover", "if TYPE_CHECKING:", "raise NotImplementedError", "\\.\\.\\."]

causeway-0.1.0/src/causeway/__init__.py

@@ -0,0 +1,68 @@
+"""Causeway — a lean backend framework for type-safe Python APIs.
+
+Public API surface for v0.1. Anything not listed in ``__all__`` (or imported
+from a private underscore module like ``causeway._methods``) is implementation
+detail and may change in any release. See ``docs/semver.md``.
+
+Slice landed in this release:
+
+- File-based routing primitives — :func:`get` / :func:`post` / :func:`put` /
+  :func:`patch` / :func:`delete` decorators, :func:`causeway.routing.discover` and
+  :func:`causeway.routing.register` for the walker.
+- Scopes — :func:`provide` for ``_scope.py`` providers.
+- Middleware — :class:`Middleware` base class and :func:`guard` decorator.
+- Config — :class:`Settings` (re-export of ``pydantic_settings.BaseSettings``)
+  and :class:`Manifest` (parsed ``causeway.toml``).
+
+Re-exported from ``dyadpy`` so app code only depends on ``causeway``:
+
+- :func:`Depends` — DI marker for handler parameters.
+- :func:`raises` — declare exception types the handler may raise (flows to
+  the generated TS client's ``Result<T, E>`` union).
+- :func:`stream` — SSE return type marker.
+- :data:`Bytes` — raw-body sentinel.
+"""
+
+from __future__ import annotations
+
+from dyadpy import Bytes, Depends, raises, stream
+
+from causeway import errors
+from causeway._methods import delete, get, patch, post, put
+from causeway.app import create_app
+from causeway.config import Manifest, Settings
+from causeway.middleware import Middleware, guard
+from causeway.observability import RequestIdMiddleware, configure_logging, configure_otel
+from causeway.plugins import env, register
+from causeway.scope import provide
+from causeway.tasks import cron, task, tasks_eager
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Bytes",
+    "Depends",
+    "Manifest",
+    "Middleware",
+    "RequestIdMiddleware",
+    "Settings",
+    "__version__",
+    "configure_logging",
+    "configure_otel",
+    "create_app",
+    "cron",
+    "delete",
+    "env",
+    "errors",
+    "get",
+    "guard",
+    "patch",
+    "post",
+    "provide",
+    "put",
+    "raises",
+    "register",
+    "stream",
+    "task",
+    "tasks_eager",
+]

causeway-0.1.0/src/causeway/_cron.py

@@ -0,0 +1,65 @@
+"""Tiny crontab parser.
+
+Five fields: minute hour day-of-month month day-of-week. Each field is one
+of: ``*``, an integer, a comma list ``1,3,5``, or a step ``*/N``. That's
+all we need for the in-process reference adapter — production adapters
+delegate to their own scheduler.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timedelta
+
+_FIELD_RANGES = [
+    (0, 59),  # minute
+    (0, 23),  # hour
+    (1, 31),  # day of month
+    (1, 12),  # month
+    (0, 6),  # day of week (0=Mon...6=Sun for simplicity)
+]
+
+
+def _parse_field(spec: str, lo: int, hi: int) -> set[int]:
+    if spec == "*":
+        return set(range(lo, hi + 1))
+    if spec.startswith("*/"):
+        step = int(spec[2:])
+        return set(range(lo, hi + 1, step))
+    out: set[int] = set()
+    for piece in spec.split(","):
+        out.add(int(piece))
+    return out
+
+
+def _matches(expr: str, now: datetime) -> bool:
+    parts = expr.split()
+    if len(parts) != 5:
+        msg = f"cron expr must be 5 fields: {expr!r}"
+        raise ValueError(msg)
+    minute, hour, dom, month, dow = (
+        _parse_field(p, *_FIELD_RANGES[i]) for i, p in enumerate(parts)
+    )
+    return (
+        now.minute in minute
+        and now.hour in hour
+        and now.day in dom
+        and now.month in month
+        # weekday(): Mon=0..Sun=6 — matches our field convention.
+        and now.weekday() in dow
+    )
+
+
+def next_fire(expr: str, after: datetime) -> float:
+    """Seconds until the next minute that matches ``expr`` after ``after``.
+
+    Scans minute-by-minute up to 31 days ahead — fine for the in-memory
+    reference adapter. If no match is found, raises.
+    """
+    candidate = (after + timedelta(minutes=1)).replace(second=0, microsecond=0)
+    end = candidate + timedelta(days=31)
+    while candidate < end:
+        if _matches(expr, candidate):
+            return (candidate - after).total_seconds()
+        candidate += timedelta(minutes=1)
+    msg = f"no cron match within 31 days for {expr!r}"
+    raise ValueError(msg)