tenchi 0.1.0__tar.gz

tenchi-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,20 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  checks:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+      - run: uv sync --locked
+      - run: uv run ruff format --check .
+      - run: uv run ruff check .
+      - run: uv run pyright
+      - run: uv run pytest

tenchi-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,34 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+      - run: uv sync --locked
+      - name: Check tag matches project version
+        if: github.ref_type == 'tag'
+        run: |
+          version=$(uv run python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          if [ "v${version}" != "${GITHUB_REF_NAME}" ]; then
+            echo "Tag ${GITHUB_REF_NAME} does not match project version v${version}"
+            exit 1
+          fi
+      - run: uv run ruff format --check .
+      - run: uv run ruff check .
+      - run: uv run pyright
+      - run: uv run pytest
+      - run: uv build
+      - run: uv publish --trusted-publishing always

tenchi-0.1.0/.gitignore

@@ -0,0 +1,219 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+todos.db

tenchi-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Taylor Bryant
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tenchi-0.1.0/PKG-INFO

@@ -0,0 +1,403 @@
+Metadata-Version: 2.4
+Name: tenchi
+Version: 0.1.0
+Summary: A contract-first, Python-native framework for building REST APIs around use cases, ports, and explicit wiring.
+Project-URL: Homepage, https://github.com/taylorbryant/tenchi
+Project-URL: Repository, https://github.com/taylorbryant/tenchi
+Project-URL: Issues, https://github.com/taylorbryant/tenchi/issues
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,asgi,contracts,framework,pydantic,rest,starlette
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.7
+Requires-Dist: starlette>=0.37
+Requires-Dist: typing-extensions>=4.10
+Description-Content-Type: text/markdown
+
+# Tenchi
+
+Tenchi is a contract-first, Python-native framework for building REST APIs
+around use cases, ports, and explicit dependency wiring. It is the Python
+sibling of Beignet: the same architecture — contracts at the HTTP boundary,
+use cases at the center, protocol-based ports, infrastructure adapters, and
+explicit server composition — expressed with plain functions, dataclasses,
+`typing.Protocol`, Pydantic v2, and Starlette instead of TypeScript
+machinery.
+
+## Installation
+
+Tenchi requires Python 3.12+.
+
+```sh
+uv add tenchi          # or: pip install tenchi
+```
+
+To work on this repository:
+
+```sh
+uv sync                # install the package and dev tools
+uv run pytest          # tests (framework + todos example)
+uv run ruff check .    # lint
+uv run pyright         # strict type checking
+```
+
+## Architecture
+
+Applications follow a prescriptive structure. Each feature owns its
+contracts, schemas, ports, routes, use cases, and tests; infrastructure
+implements ports; server composition owns concrete wiring:
+
+```txt
+app/
+  features/
+    todos/
+      contracts.py        # HTTP boundary: method, path, request/response, errors
+      schemas.py          # Pydantic models shared by contracts, use cases, ports
+      ports.py            # typing.Protocol interfaces the feature needs
+      routes.py           # binds contracts to use cases
+      use_cases/          # application workflows (plain async functions)
+      tests/              # use-case tests, no HTTP required
+  shared/
+    errors.py             # application error definitions with stable codes
+  infra/
+    memory_todo_repository.py   # concrete port implementations
+    port_wiring.py              # constructs concrete adapters
+  server/
+    context.py            # AppContext dataclass holding ports
+    routes.py             # composes feature route groups
+    asgi.py               # concrete wiring + ASGI app
+tests/                    # HTTP integration tests
+```
+
+Dependency direction is strict: schemas and use cases never import
+infrastructure or the HTTP runtime; routes bind contracts to use cases but
+construct nothing concrete; only `server/` (and `infra/`) know which
+implementations are in play.
+
+## The basic flow
+
+Schemas are ordinary Pydantic models:
+
+```python
+# app/features/todos/schemas.py
+from pydantic import BaseModel
+
+class CreateTodo(BaseModel):
+    title: str
+
+class Todo(BaseModel):
+    id: str
+    title: str
+    completed: bool
+```
+
+Ports describe what application code needs, as protocols:
+
+```python
+# app/features/todos/ports.py
+from typing import Protocol
+from .schemas import Todo
+
+class TodoRepository(Protocol):
+    async def create(self, *, title: str) -> Todo: ...
+    async def list(self) -> list[Todo]: ...
+```
+
+The application context is a frozen dataclass of ports:
+
+```python
+# app/server/context.py
+from dataclasses import dataclass
+from app.features.todos.ports import TodoRepository
+
+@dataclass(frozen=True, slots=True)
+class AppContext:
+    todos: TodoRepository
+```
+
+Use cases are plain async functions — no base classes, no decorators:
+
+```python
+# app/features/todos/use_cases/create_todo.py
+from app.server.context import AppContext
+from ..schemas import CreateTodo, Todo
+
+async def create_todo(request: CreateTodo, context: AppContext) -> Todo:
+    return await context.todos.create(title=request.title)
+```
+
+Contracts define and validate the HTTP boundary. Any type Pydantic can
+validate works, including `list[Todo]`:
+
+```python
+# app/features/todos/contracts.py
+from tenchi.contracts import contract
+from .schemas import CreateTodo, Todo
+
+create_todo_contract = contract(
+    method="POST",
+    path="/todos",
+    request=CreateTodo,
+    response=Todo,
+    status=201,
+)
+```
+
+Contracts can also carry documentation metadata (`summary=`,
+`description=`, `tags=`, `deprecated=`) and non-JSON media types: pair
+`request_media_type="text/plain"` with `request=str`, or
+`"application/octet-stream"` with `bytes`, and the server, client, and
+OpenAPI document all follow (useful for webhook endpoints that need the
+raw body).
+
+Contracts can also declare path parameters (`params=`) and query parameters
+(`query=`), each validated into its own model and passed to the use case as
+a keyword argument of the same name:
+
+```python
+class ListTodosQuery(BaseModel):
+    completed: bool | None = None
+
+list_todos_contract = contract(
+    method="GET",
+    path="/todos",
+    query=ListTodosQuery,
+    response=list[Todo],
+)
+
+async def list_todos(query: ListTodosQuery, context: AppContext) -> list[Todo]:
+    ...
+```
+
+Routes bind contracts to use cases. Binding is validated eagerly, so a use
+case that cannot accept what its contract declares fails at import time:
+
+```python
+# app/features/todos/routes.py
+from tenchi.routes import route, route_group
+from .contracts import create_todo_contract
+from .use_cases.create_todo import create_todo
+
+routes = route_group(
+    route(create_todo_contract, create_todo),
+)
+```
+
+Server composition owns concrete wiring and produces the ASGI app. The
+lifespan owns process-scoped resources — it opens them at startup, closes
+them at shutdown, and whatever it yields is handed to the context factory,
+which runs once per request:
+
+```python
+# app/server/asgi.py
+from collections.abc import AsyncGenerator
+from contextlib import asynccontextmanager
+
+from tenchi.server import create_app
+from app.features.todos.ports import TodoRepository
+from app.infra.port_wiring import open_todo_repository
+from app.server.context import AppContext
+from app.server.routes import routes
+
+@asynccontextmanager
+async def lifespan() -> AsyncGenerator[TodoRepository]:
+    async with open_todo_repository("todos.db") as todos:
+        yield todos
+
+def create_context(todos: TodoRepository) -> AppContext:
+    return AppContext(todos=todos)
+
+app = create_app(routes=routes, context_factory=create_context, lifespan=lifespan)
+```
+
+For apps without real resources, `lifespan` is optional and the context
+factory can take zero arguments and close over module-scoped objects (see
+the memory-backed fixtures in the example tests).
+
+Run it with any ASGI server:
+
+```sh
+uvicorn app.server.asgi:app --reload
+curl -X POST localhost:8000/todos -H 'content-type: application/json' \
+  -d '{"title": "Buy milk"}'
+```
+
+## Typed client
+
+The same contracts drive a typed `httpx`-based client — no code generation,
+no drift. `call()` returns the contract's response type, so `todo` below is
+statically a `Todo` and `todos` a `list[Todo]`:
+
+```python
+from tenchi.client import Client
+
+async with Client(base_url="http://localhost:8000") as client:
+    todo = await client.call(create_todo_contract, request=CreateTodo(title="Buy milk"))
+    todos = await client.call(list_todos_contract, query=ListTodosQuery(completed=False))
+```
+
+Declared errors come back as the same `AppError` the server raised, carrying
+the same `ErrorDef`; anything undeclared raises `UnexpectedResponseError`:
+
+```python
+try:
+    await client.call(get_todo_contract, params=GetTodoParams(todo_id="missing"))
+except AppError as err:
+    assert err.definition == todo_not_found
+```
+
+For tests, pass your own `httpx.AsyncClient` with an `ASGITransport` via
+`Client(http=...)` to call the app in-process.
+
+## Errors
+
+Application errors carry a stable code, an HTTP status, and optional
+structured details. Contracts declare the errors they are expected to
+return; declared errors map to their status, and everything else — including
+undeclared `AppError`s — becomes a framework-owned 500 so contracts stay
+honest:
+
+```python
+# app/shared/errors.py
+from tenchi.errors import ErrorDef
+
+todo_not_found = ErrorDef(code="TODO_NOT_FOUND", status=404, message="Todo not found")
+```
+
+```python
+# in a use case
+raise AppError(todo_not_found, details={"todo_id": params.todo_id})
+```
+
+Errors can carry response headers — declare the names on the definition
+(they appear in the OpenAPI document) and set values per instance:
+
+```python
+throttled = ErrorDef(code="THROTTLED", status=429, message="Slow down",
+                     headers=("Retry-After",))
+raise AppError(throttled, headers={"Retry-After": "30"})
+```
+
+```python
+# in a contract
+get_todo_contract = contract(
+    method="GET",
+    path="/todos/{todo_id}",
+    params=GetTodoParams,
+    response=Todo,
+    errors=(todo_not_found,),
+)
+```
+
+Error responses use a flat envelope, `{"code", "message", "details"?}`, and
+every error response carries an `x-tenchi-error-source` header set to `app`
+or `framework` so the two are always distinguishable.
+
+## Testing
+
+Use cases test without HTTP — construct a context with a fake or memory
+adapter and call the function:
+
+```python
+async def test_create_todo() -> None:
+    context = AppContext(todos=MemoryTodoRepository())
+    todo = await create_todo(CreateTodo(title="Buy milk"), context)
+    assert todo.title == "Buy milk"
+```
+
+Integration tests exercise the full boundary with `httpx.ASGITransport`; see
+`examples/todos/tests/test_todos_http.py`. When the app uses a lifespan,
+wrap it in `asgi-lifespan`'s `LifespanManager` so startup and shutdown run
+(`ASGITransport` alone does not trigger lifespan events); see
+`examples/todos/tests/test_todos_lifespan.py`.
+
+## OpenAPI
+
+Contracts carry everything an OpenAPI document needs, so generation is a
+pure function — no decorators, no runtime introspection of handlers:
+
+```python
+from tenchi.openapi import openapi_schema
+
+document = openapi_schema(api_routes, title="Todos", version="0.1.0")
+```
+
+Request bodies use validation-mode JSON Schema, responses use
+serialization mode, path/query parameters come from the `params`/`query`
+models, declared errors appear as error responses under their status with
+the standard envelope schema, and routes with validated input document the
+framework's 422 automatically.
+
+To serve the document, compose `openapi_route` alongside your routes in
+`server/routes.py` — it is generated once at startup and served by the same
+route machinery it describes (and it does not document itself):
+
+```python
+from tenchi.openapi import openapi_route
+
+api_routes = route_group(todo_routes)
+routes = route_group(
+    api_routes,
+    openapi_route(api_routes, title="Todos", version="0.1.0"),
+)
+```
+
+## CLI
+
+```sh
+tenchi new my_app                      # scaffold a new application
+tenchi make feature notes              # generate a feature skeleton
+tenchi make use-case notes create_note # generate a use-case stub and test
+tenchi routes                          # print the bound route table
+tenchi openapi [-o openapi.json]       # print or write the OpenAPI document
+tenchi dev                             # serve app.server.asgi:app with reload
+```
+
+Generators create files and print wiring instructions — they never edit
+existing modules, because dependency wiring stays explicit and app-owned.
+Everything they generate passes Ruff, Pyright strict, and pytest as-is.
+
+`tenchi new` generates the todos starter — feature, ports, memory adapter,
+wiring, and passing tests — so a new project starts from a working vertical
+slice:
+
+```sh
+uv run tenchi new my_app
+cd my_app && uv sync && uv run pytest
+```
+
+`tenchi routes` prints every bound route with its status, use case, and
+declared error codes:
+
+```txt
+POST  /todos            201  app.features.todos.use_cases.create_todo.create_todo
+GET   /todos            200  app.features.todos.use_cases.list_todos.list_todos
+GET   /todos/{todo_id}  200  app.features.todos.use_cases.get_todo.get_todo  [TODO_NOT_FOUND]
+GET   /openapi.json     200  tenchi.openapi.openapi_route.<locals>.get_openapi
+```
+
+## Example
+
+A complete todos application using the prescribed structure lives in
+[`examples/todos/`](examples/todos/). It ships two adapters for the same
+port: the SQLite repository (aiosqlite) wired into the running app through
+the lifespan, and the memory repository used by unit tests — swapping them
+touches only `infra/` and `server/`.
+
+## Status
+
+Tenchi is an early vertical slice: contracts (body, path, and query
+validation), route binding, ASGI dispatch, lifespan-managed resources with
+request-scoped context, ports, expected-error mapping, a contract-driven
+typed client, OpenAPI 3.1 generation, and a CLI (`new`, `make feature`,
+`make use-case`, `routes`, `openapi`, `dev`). `tenchi doctor` and
+provider-backed infrastructure are planned but intentionally not started.