takibiapi 0.1.0__tar.gz

takibiapi-0.1.0/Cargo.lock

@@ -0,0 +1,133 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "heck"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea"
+
+[[package]]
+name = "libc"
+version = "0.2.191"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "65cd87c9a6d60536580b316ad985726104730a5151c99845f2490428ef91240a"
+
+[[package]]
+name = "once_cell"
+version = "1.21.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
+
+[[package]]
+name = "portable-atomic"
+version = "1.15.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "05c8b63e8d9609db387f0324918f81d68fe27748f084ef092fb35954d0539a85"
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.107"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "pyo3"
+version = "0.29.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "700d18fa267b73b9b521fd7e13580e2f446916f176cacee1ab63fcc8191f1655"
+dependencies = [
+ "libc",
+ "once_cell",
+ "portable-atomic",
+ "pyo3-build-config",
+ "pyo3-ffi",
+ "pyo3-macros",
+]
+
+[[package]]
+name = "pyo3-build-config"
+version = "0.29.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7b3fc0c4d08f6bb10e71fe39dfb9e2f59c6eb6854e22ec8092f50c69a4499adb"
+dependencies = [
+ "target-lexicon",
+]
+
+[[package]]
+name = "pyo3-ffi"
+version = "0.29.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dfc0b8e19df29aad7086cf977bb0c2a2f143e30567eb113e9cf72b62ca698330"
+dependencies = [
+ "libc",
+ "pyo3-build-config",
+]
+
+[[package]]
+name = "pyo3-macros"
+version = "0.29.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6100e8a4b5eba53afaa5ed078364851a0b2499c553a44c31026b929049b49dc6"
+dependencies = [
+ "proc-macro2",
+ "pyo3-macros-backend",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "pyo3-macros-backend"
+version = "0.29.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6143877a16e82b5a727b7127ff4cd86858a24a28d745d72f43e6f227c7b1bdb3"
+dependencies = [
+ "heck",
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.47"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "syn"
+version = "2.0.119"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "872831b642d1a07999a962a351ed35b955ea2cfc8f3862091e2a240a84f17297"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "takibiapi"
+version = "0.0.0"
+dependencies = [
+ "pyo3",
+ "pyo3-build-config",
+]
+
+[[package]]
+name = "target-lexicon"
+version = "0.13.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "adb6935a6f5c20170eeceb1a3835a49e12e19d792f6dd344ccc76a985ca5a6ca"
+
+[[package]]
+name = "unicode-ident"
+version = "1.0.27"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a2c754d6c33795a1c324727428e5a7dedb5b06195f9890bdbcba760d3e246563"

takibiapi-0.1.0/Cargo.toml

@@ -0,0 +1,23 @@
+# Cargo workspace. The Rust extension crate lives next to its pyproject.toml in pypi/takibiapi,
+# so that directory is both a uv and a Cargo workspace member. The crate has no version of its own:
+# maturin takes the package version from pyproject.toml. Bazel reads this workspace and Cargo.lock
+# too (MODULE.bazel), so the crates are pinned once. The lint levels are crate attributes in
+# pypi/takibiapi/src/lib.rs, where both build systems see them.
+[workspace]
+resolver = "2"
+members = ["pypi/takibiapi"]
+
+[workspace.package]
+edition = "2021"
+rust-version = "1.83"
+license = "MIT"
+repository = "https://github.com/nakita628/takibi"
+
+[workspace.dependencies]
+pyo3 = "0.29"
+pyo3-build-config = { version = "0.29", features = ["resolve-config"] }
+
+[profile.release]
+lto = "fat"
+codegen-units = 1
+opt-level = 3

takibiapi-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 - present, takibiapi Contributors
+
+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.

takibiapi-0.1.0/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: takibiapi
+Version: 0.1.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Rust
+Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
+Classifier: Typing :: Typed
+License-File: LICENSE
+Summary: REST APIs whose OpenAPI document, request checks and handler types come from Python's own types
+Keywords: openapi,asgi,rsgi,rest,api,typing,dataclasses,typeddict
+Author: nakita628
+License-Expression: MIT
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Issues, https://github.com/nakita628/takibi/issues
+Project-URL: Repository, https://github.com/nakita628/takibi
+
+# TakibiAPI
+
+REST APIs whose OpenAPI document, request checks and handler types come from Python's own types (dataclasses, `TypedDict`, `Literal`, `Enum`, `Annotated`). No runtime dependencies; JSON, routing and type checks run in a Rust extension. ASGI and Granian's RSGI.
+
+```sh
+pip install takibiapi
+```
+
+## Quick start
+
+```python
+from dataclasses import dataclass
+
+from takibiapi import Context, TakibiAPI, createRoute
+
+
+@dataclass
+class Message:
+    message: str
+
+
+class getTakibiRoute(
+    createRoute(
+        {
+            "method": "get",
+            "path": "/takibi",
+            "responses": {200: {"description": "takibi🔥", "content": {"application/json": {"schema": Message}}}},
+        }
+    )
+):
+    """Say takibi🔥."""
+
+
+def getTakibiRouteHandler(c: Context[getTakibiRoute]):
+    return c.json(Message("takibi🔥"))
+
+
+app = TakibiAPI()
+app.openapi(getTakibiRoute, getTakibiRouteHandler)
+app.doc("/doc", {"openapi": "3.1.0", "info": {"title": "takibi API", "version": "1.0.0"}})
+```
+
+```bash
+granian --interface rsgi myapp:app   # or: uvicorn myapp:app
+curl localhost:8000/takibi           # {"message":"takibi🔥"}
+```
+
+## Routes and handlers
+
+A route is a class made with `createRoute`, and its handler takes `c: Context[thatRoute]`. `app.openapi(route, handler)` raises `TypeError` for anything else, and the type checker sees the route's types: `c.req.valid(...)` is the declared request type and `c.json(...)` takes only the declared responses.
+
+## Requests
+
+The request parts in `request` (`params`, `query`, `headers`, `cookies`, a JSON `body`) are checked against their **types** before the handler runs and read with `c.req.valid("param" | "query" | "header" | "cookie" | "json")`:
+
+```python
+params = c.req.valid("param")  # "/todos/7" -> {"todoId": 7}: text converted to the declared int
+```
+
+Only types are checked: `Annotated` keywords (`minLength`, `maximum`, ...) are written to the document but not checked, and responses are not checked at run time. For those, use [pydantic-takibiapi](../pydantic-takibiapi) or [zopy-takibiapi](../zopy-takibiapi).
+
+A wrong type gets **422** Problem Details (`errors: [{in, path, code, message}]`), invalid JSON **400**, a required body with another Content-Type **415**.
+
+## Errors
+
+```python
+app.onError(lambda c: c.json({"error": str(c.error)}, 500))  # exceptions from handlers and middleware
+app.notFound(lambda c: c.text("not here", 404))  # paths with no route
+```
+
+Both take handlers `def h(c)` (the exception is `c.error`) and middleware `async def mw(c, next)`, and registrations compose instead of replacing each other: middleware runs around the handlers registered after it (`await next()` is their response, `None` when none answered), a handler ends the chain by returning a response, and `prefix="/api"` limits a registration to those paths. The handlers of a mounted app (`app.route("/v1", v1)`) come first for its paths, then the parent's in registration order.
+
+```python
+async def report(c, next):
+    res = await next()
+    log.warning("%s %s -> %s", c.req.method, c.req.path, res.status if res else "default")
+    return res
+
+
+app.onError(report, lambda c: c.text("API failed", 500), prefix="/api")
+app.notFound(report, lambda c: c.text("no such API", 404), prefix="/api")
+```
+
+Without them, Takibi answers 500 / 404 Problem Details (and 405 with `Allow` for a known path), which also answer when a chain ends without a response.
+
+## Middleware and CORS
+
+`app.use(middleware, prefix="/api")` runs `async def mw(c, next)` around the handlers. CORS, as Hono's `hono/cors`:
+
+```python
+from takibiapi.cors import cors
+
+app.use(cors())  # Access-Control-Allow-Origin: *
+app.use(cors({"origin": ["https://a.example"], "credentials": True, "maxAge": 600}), prefix="/api")
+```
+
+Options: `origin` (`"*"`, an origin, a list, or `(origin, c) -> origin | None`), `allowMethods`, `allowHeaders`, `exposeHeaders`, `maxAge`, `credentials`. Preflights (`OPTIONS`) are answered with 204.
+
+## Cookies
+
+`takibiapi.cookie` reads and sets cookies, plain or signed:
+
+```python
+from takibiapi.cookie import deleteCookie, getCookie, getSignedCookie, setCookie, setSignedCookie
+
+
+def getProfileRouteHandler(c: Context[getProfileRoute]):
+    theme = getCookie(c, "theme")  # str | None; getCookie(c) is every cookie as a dict
+    session = getSignedCookie(c, secret, "session")  # the value, False if tampered with, None if absent
+    setCookie(c, "theme", "dark", {"maxAge": 86400, "httpOnly": True, "sameSite": "Lax"})
+    setSignedCookie(c, "session", "42", secret)
+    deleteCookie(c, "old")  # Max-Age=0; returns the value the request carried
+    return c.json(profile)
+```
+
+`setCookie` adds a `Set-Cookie` header to the response the handler returns (`c.header(name, value, append=True)` underneath); `path` is `/` unless given, and the options are the header's attributes (`domain`, `expires`, `httpOnly`, `maxAge`, `path`, `secure`, `sameSite`, `priority`, `partitioned`) plus `prefix`: `"secure"` names the cookie `__Secure-<name>`, `"host"` `__Host-<name>`, each with the attributes it requires. A signed cookie carries an HMAC-SHA256 of its value, in the format Takibi (npm) uses, so the two read each other's cookies with the same secret. `generateCookie` / `generateSignedCookie` give the header value alone.
+
+## OpenAPI
+
+`app.doc(path, config)` serves the document and `app.getOpenAPIDocument(config)` returns it; `config` must give `openapi` (3.0.x or 3.1.x) and `info`. Dataclasses, `TypedDict`s and `Enum`s become `components.schemas`. Swagger UI: [takibi-swagger-ui](../takibi-swagger-ui).
+
+## Development
+
+From the repository root: `bazel test //pypi/takibiapi:test` runs this package's tests (on both the Rust engine and the pure-Python reference); `uv sync` builds the extension into the virtualenv for the editor. See the root README.
+
+## License
+
+Distributed under the MIT License. See [LICENSE](https://github.com/nakita628/takibi/blob/main/pypi/takibiapi/LICENSE) for more information.
+

takibiapi-0.1.0/README.md

@@ -0,0 +1,128 @@
+# TakibiAPI
+
+REST APIs whose OpenAPI document, request checks and handler types come from Python's own types (dataclasses, `TypedDict`, `Literal`, `Enum`, `Annotated`). No runtime dependencies; JSON, routing and type checks run in a Rust extension. ASGI and Granian's RSGI.
+
+```sh
+pip install takibiapi
+```
+
+## Quick start
+
+```python
+from dataclasses import dataclass
+
+from takibiapi import Context, TakibiAPI, createRoute
+
+
+@dataclass
+class Message:
+    message: str
+
+
+class getTakibiRoute(
+    createRoute(
+        {
+            "method": "get",
+            "path": "/takibi",
+            "responses": {200: {"description": "takibi🔥", "content": {"application/json": {"schema": Message}}}},
+        }
+    )
+):
+    """Say takibi🔥."""
+
+
+def getTakibiRouteHandler(c: Context[getTakibiRoute]):
+    return c.json(Message("takibi🔥"))
+
+
+app = TakibiAPI()
+app.openapi(getTakibiRoute, getTakibiRouteHandler)
+app.doc("/doc", {"openapi": "3.1.0", "info": {"title": "takibi API", "version": "1.0.0"}})
+```
+
+```bash
+granian --interface rsgi myapp:app   # or: uvicorn myapp:app
+curl localhost:8000/takibi           # {"message":"takibi🔥"}
+```
+
+## Routes and handlers
+
+A route is a class made with `createRoute`, and its handler takes `c: Context[thatRoute]`. `app.openapi(route, handler)` raises `TypeError` for anything else, and the type checker sees the route's types: `c.req.valid(...)` is the declared request type and `c.json(...)` takes only the declared responses.
+
+## Requests
+
+The request parts in `request` (`params`, `query`, `headers`, `cookies`, a JSON `body`) are checked against their **types** before the handler runs and read with `c.req.valid("param" | "query" | "header" | "cookie" | "json")`:
+
+```python
+params = c.req.valid("param")  # "/todos/7" -> {"todoId": 7}: text converted to the declared int
+```
+
+Only types are checked: `Annotated` keywords (`minLength`, `maximum`, ...) are written to the document but not checked, and responses are not checked at run time. For those, use [pydantic-takibiapi](../pydantic-takibiapi) or [zopy-takibiapi](../zopy-takibiapi).
+
+A wrong type gets **422** Problem Details (`errors: [{in, path, code, message}]`), invalid JSON **400**, a required body with another Content-Type **415**.
+
+## Errors
+
+```python
+app.onError(lambda c: c.json({"error": str(c.error)}, 500))  # exceptions from handlers and middleware
+app.notFound(lambda c: c.text("not here", 404))  # paths with no route
+```
+
+Both take handlers `def h(c)` (the exception is `c.error`) and middleware `async def mw(c, next)`, and registrations compose instead of replacing each other: middleware runs around the handlers registered after it (`await next()` is their response, `None` when none answered), a handler ends the chain by returning a response, and `prefix="/api"` limits a registration to those paths. The handlers of a mounted app (`app.route("/v1", v1)`) come first for its paths, then the parent's in registration order.
+
+```python
+async def report(c, next):
+    res = await next()
+    log.warning("%s %s -> %s", c.req.method, c.req.path, res.status if res else "default")
+    return res
+
+
+app.onError(report, lambda c: c.text("API failed", 500), prefix="/api")
+app.notFound(report, lambda c: c.text("no such API", 404), prefix="/api")
+```
+
+Without them, Takibi answers 500 / 404 Problem Details (and 405 with `Allow` for a known path), which also answer when a chain ends without a response.
+
+## Middleware and CORS
+
+`app.use(middleware, prefix="/api")` runs `async def mw(c, next)` around the handlers. CORS, as Hono's `hono/cors`:
+
+```python
+from takibiapi.cors import cors
+
+app.use(cors())  # Access-Control-Allow-Origin: *
+app.use(cors({"origin": ["https://a.example"], "credentials": True, "maxAge": 600}), prefix="/api")
+```
+
+Options: `origin` (`"*"`, an origin, a list, or `(origin, c) -> origin | None`), `allowMethods`, `allowHeaders`, `exposeHeaders`, `maxAge`, `credentials`. Preflights (`OPTIONS`) are answered with 204.
+
+## Cookies
+
+`takibiapi.cookie` reads and sets cookies, plain or signed:
+
+```python
+from takibiapi.cookie import deleteCookie, getCookie, getSignedCookie, setCookie, setSignedCookie
+
+
+def getProfileRouteHandler(c: Context[getProfileRoute]):
+    theme = getCookie(c, "theme")  # str | None; getCookie(c) is every cookie as a dict
+    session = getSignedCookie(c, secret, "session")  # the value, False if tampered with, None if absent
+    setCookie(c, "theme", "dark", {"maxAge": 86400, "httpOnly": True, "sameSite": "Lax"})
+    setSignedCookie(c, "session", "42", secret)
+    deleteCookie(c, "old")  # Max-Age=0; returns the value the request carried
+    return c.json(profile)
+```
+
+`setCookie` adds a `Set-Cookie` header to the response the handler returns (`c.header(name, value, append=True)` underneath); `path` is `/` unless given, and the options are the header's attributes (`domain`, `expires`, `httpOnly`, `maxAge`, `path`, `secure`, `sameSite`, `priority`, `partitioned`) plus `prefix`: `"secure"` names the cookie `__Secure-<name>`, `"host"` `__Host-<name>`, each with the attributes it requires. A signed cookie carries an HMAC-SHA256 of its value, in the format Takibi (npm) uses, so the two read each other's cookies with the same secret. `generateCookie` / `generateSignedCookie` give the header value alone.
+
+## OpenAPI
+
+`app.doc(path, config)` serves the document and `app.getOpenAPIDocument(config)` returns it; `config` must give `openapi` (3.0.x or 3.1.x) and `info`. Dataclasses, `TypedDict`s and `Enum`s become `components.schemas`. Swagger UI: [takibi-swagger-ui](../takibi-swagger-ui).
+
+## Development
+
+From the repository root: `bazel test //pypi/takibiapi:test` runs this package's tests (on both the Rust engine and the pure-Python reference); `uv sync` builds the extension into the virtualenv for the editor. See the root README.
+
+## License
+
+Distributed under the MIT License. See [LICENSE](https://github.com/nakita628/takibi/blob/main/pypi/takibiapi/LICENSE) for more information.

takibiapi-0.1.0/pypi/takibiapi/BUILD.bazel

@@ -0,0 +1,25 @@
+load("//tools/pytest:defs.bzl", "pytest_test")
+
+# The Rust engine's sources, built into takibiapi._core by //pypi/takibiapi/python:core.
+filegroup(
+    name = "core_srcs",
+    srcs = glob(["src/**/*.rs"]),
+    visibility = ["//pypi/takibiapi/python:__pkg__"],
+)
+
+exports_files(
+    ["src/lib.rs"],
+    visibility = ["//pypi/takibiapi/python:__pkg__"],
+)
+
+# tests/test_typing.py is not here: it shells out to pyright, which `just typecheck` runs over
+# tests/typing directly.
+pytest_test(
+    name = "test",
+    size = "small",
+    tests = glob(
+        ["tests/test_*.py"],
+        exclude = ["tests/test_typing.py"],
+    ),
+    deps = ["//pypi/takibiapi/python:takibiapi"],
+)

takibiapi-0.1.0/pypi/takibiapi/CHANGELOG.md

@@ -0,0 +1,7 @@
+# takibiapi
+
+## 0.1.0
+
+### Minor Changes
+
+- Initial release

takibiapi-0.1.0/pypi/takibiapi/Cargo.toml

@@ -0,0 +1,20 @@
+[package]
+name = "takibiapi"
+description = "Rust engine (takibiapi._core) behind the takibiapi Python package: request type checks, JSON, routing"
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+repository.workspace = true
+publish = false
+readme = "README.md"
+
+[lib]
+name = "_core"
+# cdylib: the Python extension module; rlib: lets `cargo test` run pure-Rust unit tests.
+crate-type = ["cdylib", "rlib"]
+
+[dependencies]
+pyo3.workspace = true
+
+[build-dependencies]
+pyo3-build-config.workspace = true

takibiapi-0.1.0/pypi/takibiapi/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 - present, takibiapi Contributors
+
+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.

takibiapi-0.1.0/pypi/takibiapi/README.md

@@ -0,0 +1,128 @@
+# TakibiAPI
+
+REST APIs whose OpenAPI document, request checks and handler types come from Python's own types (dataclasses, `TypedDict`, `Literal`, `Enum`, `Annotated`). No runtime dependencies; JSON, routing and type checks run in a Rust extension. ASGI and Granian's RSGI.
+
+```sh
+pip install takibiapi
+```
+
+## Quick start
+
+```python
+from dataclasses import dataclass
+
+from takibiapi import Context, TakibiAPI, createRoute
+
+
+@dataclass
+class Message:
+    message: str
+
+
+class getTakibiRoute(
+    createRoute(
+        {
+            "method": "get",
+            "path": "/takibi",
+            "responses": {200: {"description": "takibi🔥", "content": {"application/json": {"schema": Message}}}},
+        }
+    )
+):
+    """Say takibi🔥."""
+
+
+def getTakibiRouteHandler(c: Context[getTakibiRoute]):
+    return c.json(Message("takibi🔥"))
+
+
+app = TakibiAPI()
+app.openapi(getTakibiRoute, getTakibiRouteHandler)
+app.doc("/doc", {"openapi": "3.1.0", "info": {"title": "takibi API", "version": "1.0.0"}})
+```
+
+```bash
+granian --interface rsgi myapp:app   # or: uvicorn myapp:app
+curl localhost:8000/takibi           # {"message":"takibi🔥"}
+```
+
+## Routes and handlers
+
+A route is a class made with `createRoute`, and its handler takes `c: Context[thatRoute]`. `app.openapi(route, handler)` raises `TypeError` for anything else, and the type checker sees the route's types: `c.req.valid(...)` is the declared request type and `c.json(...)` takes only the declared responses.
+
+## Requests
+
+The request parts in `request` (`params`, `query`, `headers`, `cookies`, a JSON `body`) are checked against their **types** before the handler runs and read with `c.req.valid("param" | "query" | "header" | "cookie" | "json")`:
+
+```python
+params = c.req.valid("param")  # "/todos/7" -> {"todoId": 7}: text converted to the declared int
+```
+
+Only types are checked: `Annotated` keywords (`minLength`, `maximum`, ...) are written to the document but not checked, and responses are not checked at run time. For those, use [pydantic-takibiapi](../pydantic-takibiapi) or [zopy-takibiapi](../zopy-takibiapi).
+
+A wrong type gets **422** Problem Details (`errors: [{in, path, code, message}]`), invalid JSON **400**, a required body with another Content-Type **415**.
+
+## Errors
+
+```python
+app.onError(lambda c: c.json({"error": str(c.error)}, 500))  # exceptions from handlers and middleware
+app.notFound(lambda c: c.text("not here", 404))  # paths with no route
+```
+
+Both take handlers `def h(c)` (the exception is `c.error`) and middleware `async def mw(c, next)`, and registrations compose instead of replacing each other: middleware runs around the handlers registered after it (`await next()` is their response, `None` when none answered), a handler ends the chain by returning a response, and `prefix="/api"` limits a registration to those paths. The handlers of a mounted app (`app.route("/v1", v1)`) come first for its paths, then the parent's in registration order.
+
+```python
+async def report(c, next):
+    res = await next()
+    log.warning("%s %s -> %s", c.req.method, c.req.path, res.status if res else "default")
+    return res
+
+
+app.onError(report, lambda c: c.text("API failed", 500), prefix="/api")
+app.notFound(report, lambda c: c.text("no such API", 404), prefix="/api")
+```
+
+Without them, Takibi answers 500 / 404 Problem Details (and 405 with `Allow` for a known path), which also answer when a chain ends without a response.
+
+## Middleware and CORS
+
+`app.use(middleware, prefix="/api")` runs `async def mw(c, next)` around the handlers. CORS, as Hono's `hono/cors`:
+
+```python
+from takibiapi.cors import cors
+
+app.use(cors())  # Access-Control-Allow-Origin: *
+app.use(cors({"origin": ["https://a.example"], "credentials": True, "maxAge": 600}), prefix="/api")
+```
+
+Options: `origin` (`"*"`, an origin, a list, or `(origin, c) -> origin | None`), `allowMethods`, `allowHeaders`, `exposeHeaders`, `maxAge`, `credentials`. Preflights (`OPTIONS`) are answered with 204.
+
+## Cookies
+
+`takibiapi.cookie` reads and sets cookies, plain or signed:
+
+```python
+from takibiapi.cookie import deleteCookie, getCookie, getSignedCookie, setCookie, setSignedCookie
+
+
+def getProfileRouteHandler(c: Context[getProfileRoute]):
+    theme = getCookie(c, "theme")  # str | None; getCookie(c) is every cookie as a dict
+    session = getSignedCookie(c, secret, "session")  # the value, False if tampered with, None if absent
+    setCookie(c, "theme", "dark", {"maxAge": 86400, "httpOnly": True, "sameSite": "Lax"})
+    setSignedCookie(c, "session", "42", secret)
+    deleteCookie(c, "old")  # Max-Age=0; returns the value the request carried
+    return c.json(profile)
+```
+
+`setCookie` adds a `Set-Cookie` header to the response the handler returns (`c.header(name, value, append=True)` underneath); `path` is `/` unless given, and the options are the header's attributes (`domain`, `expires`, `httpOnly`, `maxAge`, `path`, `secure`, `sameSite`, `priority`, `partitioned`) plus `prefix`: `"secure"` names the cookie `__Secure-<name>`, `"host"` `__Host-<name>`, each with the attributes it requires. A signed cookie carries an HMAC-SHA256 of its value, in the format Takibi (npm) uses, so the two read each other's cookies with the same secret. `generateCookie` / `generateSignedCookie` give the header value alone.
+
+## OpenAPI
+
+`app.doc(path, config)` serves the document and `app.getOpenAPIDocument(config)` returns it; `config` must give `openapi` (3.0.x or 3.1.x) and `info`. Dataclasses, `TypedDict`s and `Enum`s become `components.schemas`. Swagger UI: [takibi-swagger-ui](../takibi-swagger-ui).
+
+## Development
+
+From the repository root: `bazel test //pypi/takibiapi:test` runs this package's tests (on both the Rust engine and the pure-Python reference); `uv sync` builds the extension into the virtualenv for the editor. See the root README.
+
+## License
+
+Distributed under the MIT License. See [LICENSE](https://github.com/nakita628/takibi/blob/main/pypi/takibiapi/LICENSE) for more information.