zopy-takibiapi 0.1.0__tar.gz

zopy_takibiapi-0.1.0/LICENSE

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

zopy_takibiapi-0.1.0/PKG-INFO

@@ -0,0 +1,97 @@
+Metadata-Version: 2.4
+Name: zopy-takibiapi
+Version: 0.1.0
+Summary: takibiapi with zopy (Zod for Python) schemas, checked strictly
+Keywords: openapi,asgi,zopy,zod,rest,api,validation
+Author: nakita628
+License-Expression: MIT
+License-File: LICENSE
+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: Topic :: Internet :: WWW/HTTP :: HTTP Servers
+Classifier: Typing :: Typed
+Requires-Dist: takibiapi>=0.1.0,<0.2
+Requires-Dist: zopy>=0.1.1
+Requires-Python: >=3.12
+Project-URL: Repository, https://github.com/nakita628/takibi
+Project-URL: Issues, https://github.com/nakita628/takibi/issues
+Description-Content-Type: text/markdown
+
+# zopy-takibiapi
+
+[TakibiAPI](../takibiapi) with [zopy](https://github.com/nakita628/zopy) (Zod for Python) schemas, checked strictly: checks, unknown keys and responses included.
+
+```sh
+pip install zopy-takibiapi
+```
+
+## Quick start
+
+```python
+from zopy_takibiapi import Context, TakibiAPI, createRoute, z
+
+
+class Message(z.StrictObject):
+    message = z.string()
+
+
+MessageSchema = Message.openapi("Message")  # components.schemas.Message, referenced with $ref
+
+
+class getTakibiRoute(
+    createRoute(
+        {
+            "method": "get",
+            "path": "/takibi",
+            "responses": {200: {"description": "takibi🔥", "content": {"application/json": {"schema": MessageSchema}}}},
+        }
+    )
+):
+    """Say takibi🔥."""
+
+
+def getTakibiRouteHandler(c: Context[getTakibiRoute]):
+    return c.json(Message(message="takibi🔥"), 200)
+
+
+app = TakibiAPI()
+app.openapi(getTakibiRoute, getTakibiRouteHandler)
+app.doc("/doc", {"openapi": "3.0.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🔥"}
+```
+
+Import `TakibiAPI` and `z` from `zopy_takibiapi`; everything else works as in Takibi.
+
+## Schemas
+
+Every object, nested ones included, must be `z.StrictObject`; `app.openapi` raises `TypeError` for a loose object or a non-zopy schema. Parameters arrive as text and are parsed as Zod parses them, so convert explicitly: `todoId = z.coerce.number().int()`.
+
+## Checks
+
+- **Requests**: `c.req.valid(...)` gives the parsed value. A failure gets **422** with Zod's issue codes as `code`.
+- **Responses**: `c.json(value, status)` encodes `value` with the schema declared for that status (`safeEncode`: checked, codecs to their wire form). A mismatch raises `ResponseValidationError` and answers **500** (details in the log, not in the response).
+
+```python
+app.onError(lambda c: c.json({"error": str(c.error)}, 500))  # replaces the 500, ResponseValidationError included
+```
+
+## OpenAPI
+
+As in Zod, only `.openapi("Name")` schemas become components; others are written in place. Documents come from zopy's `toJSONSchema` (`openapi-3.0` or JSON Schema 2020-12).
+
+## Development
+
+From the repository root: `bazel test //pypi/zopy-takibiapi:test`. See the root README.
+
+## License
+
+Distributed under the MIT License. See [LICENSE](https://github.com/nakita628/takibi/blob/main/pypi/zopy-takibiapi/LICENSE) for more information.

zopy_takibiapi-0.1.0/README.md

@@ -0,0 +1,73 @@
+# zopy-takibiapi
+
+[TakibiAPI](../takibiapi) with [zopy](https://github.com/nakita628/zopy) (Zod for Python) schemas, checked strictly: checks, unknown keys and responses included.
+
+```sh
+pip install zopy-takibiapi
+```
+
+## Quick start
+
+```python
+from zopy_takibiapi import Context, TakibiAPI, createRoute, z
+
+
+class Message(z.StrictObject):
+    message = z.string()
+
+
+MessageSchema = Message.openapi("Message")  # components.schemas.Message, referenced with $ref
+
+
+class getTakibiRoute(
+    createRoute(
+        {
+            "method": "get",
+            "path": "/takibi",
+            "responses": {200: {"description": "takibi🔥", "content": {"application/json": {"schema": MessageSchema}}}},
+        }
+    )
+):
+    """Say takibi🔥."""
+
+
+def getTakibiRouteHandler(c: Context[getTakibiRoute]):
+    return c.json(Message(message="takibi🔥"), 200)
+
+
+app = TakibiAPI()
+app.openapi(getTakibiRoute, getTakibiRouteHandler)
+app.doc("/doc", {"openapi": "3.0.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🔥"}
+```
+
+Import `TakibiAPI` and `z` from `zopy_takibiapi`; everything else works as in Takibi.
+
+## Schemas
+
+Every object, nested ones included, must be `z.StrictObject`; `app.openapi` raises `TypeError` for a loose object or a non-zopy schema. Parameters arrive as text and are parsed as Zod parses them, so convert explicitly: `todoId = z.coerce.number().int()`.
+
+## Checks
+
+- **Requests**: `c.req.valid(...)` gives the parsed value. A failure gets **422** with Zod's issue codes as `code`.
+- **Responses**: `c.json(value, status)` encodes `value` with the schema declared for that status (`safeEncode`: checked, codecs to their wire form). A mismatch raises `ResponseValidationError` and answers **500** (details in the log, not in the response).
+
+```python
+app.onError(lambda c: c.json({"error": str(c.error)}, 500))  # replaces the 500, ResponseValidationError included
+```
+
+## OpenAPI
+
+As in Zod, only `.openapi("Name")` schemas become components; others are written in place. Documents come from zopy's `toJSONSchema` (`openapi-3.0` or JSON Schema 2020-12).
+
+## Development
+
+From the repository root: `bazel test //pypi/zopy-takibiapi:test`. See the root README.
+
+## License
+
+Distributed under the MIT License. See [LICENSE](https://github.com/nakita628/takibi/blob/main/pypi/zopy-takibiapi/LICENSE) for more information.

zopy_takibiapi-0.1.0/pyproject.toml

@@ -0,0 +1,50 @@
+[project]
+name = "zopy-takibiapi"
+version = "0.1.0"
+description = "takibiapi with zopy (Zod for Python) schemas, checked strictly"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = [
+    "openapi",
+    "asgi",
+    "zopy",
+    "zod",
+    "rest",
+    "api",
+    "validation",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Internet :: WWW/HTTP :: HTTP Servers",
+    "Typing :: Typed",
+]
+dependencies = [
+    "takibiapi>=0.1.0,<0.2",
+    "zopy>=0.1.1",
+]
+
+[[project.authors]]
+name = "nakita628"
+
+[project.urls]
+Repository = "https://github.com/nakita628/takibi"
+Issues = "https://github.com/nakita628/takibi/issues"
+
+[build-system]
+requires = ["uv_build>=0.8,<0.14"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-root = "python"
+module-name = "zopy_takibiapi"
+
+[tool.uv.sources.takibiapi]
+workspace = true

zopy_takibiapi-0.1.0/pyproject.toml.orig

@@ -0,0 +1,37 @@
+[project]
+name = "zopy-takibiapi"
+version = "0.1.0"
+description = "takibiapi with zopy (Zod for Python) schemas, checked strictly"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "nakita628" }]
+keywords = ["openapi", "asgi", "zopy", "zod", "rest", "api", "validation"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Internet :: WWW/HTTP :: HTTP Servers",
+    "Typing :: Typed",
+]
+dependencies = ["takibiapi>=0.1.0,<0.2", "zopy>=0.1.1"]
+
+[project.urls]
+Repository = "https://github.com/nakita628/takibi"
+Issues = "https://github.com/nakita628/takibi/issues"
+
+[build-system]
+requires = ["uv_build>=0.8,<0.14"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-root = "python"
+module-name = "zopy_takibiapi"
+
+[tool.uv.sources]
+takibiapi = { workspace = true }

zopy_takibiapi-0.1.0/python/zopy_takibiapi/__init__.py

@@ -0,0 +1,53 @@
+"""zopy-takibiapi: takibi with zopy (Zod for Python) schemas, checked strictly.
+
+    from zopy_takibiapi import Context, Response, TakibiAPI, createRoute, z
+
+Schemas are zopy's (``z.StrictObject`` classes, ``z.string().min(1)``, ...), named for the
+document with ``.openapi("Todo")``. Requests are parsed with them before the handler runs, checks
+included, and responses are encoded with them; every object must reject unknown keys.
+"""
+
+from zopy import z
+
+from takibiapi import (
+    Context,
+    Middleware,
+    Next,
+    OpenAPIConfig,
+    Request,
+    RequestConfig,
+    Response,
+    ResponseConfig,
+    ResponseValidationError,
+    Route,
+    RouteConfig,
+    ValidationError,
+    createRoute,
+    problem,
+)
+from zopy_takibiapi.app import TakibiAPI
+from zopy_takibiapi.problems import ValidationErrorItem, ValidationProblem
+from zopy_takibiapi.schemas import ZopySchemas
+
+__all__ = [
+    "Context",
+    "Middleware",
+    "Next",
+    "OpenAPIConfig",
+    "Request",
+    "RequestConfig",
+    "Response",
+    "ResponseConfig",
+    "ResponseValidationError",
+    "Route",
+    "RouteConfig",
+    "TakibiAPI",
+    "ValidationError",
+    "ValidationErrorItem",
+    "ValidationProblem",
+    "ZopySchemas",
+    "createRoute",
+    "problem",
+    "z",
+]
+__version__ = "0.1.0"

zopy_takibiapi-0.1.0/python/zopy_takibiapi/app.py

@@ -0,0 +1,21 @@
+"""``TakibiAPI``: takibi with zopy (Zod for Python) schemas."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import takibiapi
+
+from .schemas import ZopySchemas
+
+
+class TakibiAPI(takibiapi.TakibiAPI):
+    """``takibiapi.TakibiAPI`` whose routes are described with zopy schemas: requests are parsed with
+    them before the handler runs (422 when they do not match), and ``c.json(...)`` encodes the
+    response with the declared schema (500 when the handler breaks its own contract). Everything
+    else (routing, middleware, ASGI / RSGI, the OpenAPI document) is takibi's."""
+
+    schemas: Any = ZopySchemas()
+
+
+__all__ = ["TakibiAPI"]

zopy_takibiapi-0.1.0/python/zopy_takibiapi/problems.py

@@ -0,0 +1,38 @@
+"""The RFC 9457 Problem Details body answered when a request part does not match its schema."""
+
+from __future__ import annotations
+
+from typing import Any, cast
+
+from zopy import z
+
+# "in" is a Python keyword, so this one shape is built from a namespace instead of a class body.
+ValidationErrorItem: Any = cast(Any, type(z.StrictObject))(
+    "ValidationErrorItem",
+    (z.StrictObject,),
+    {
+        "in": z.enum(("path", "query", "header", "cookie", "body")).openapi(
+            {"description": "Where the value was sent (an OpenAPI parameter location, or body)"}
+        ),
+        "path": z.string().openapi({"description": "Dot-separated path inside that part", "example": "title"}),
+        "code": z.string().openapi({"description": "The Zod issue code", "example": "too_small"}),
+        "message": z.string().openapi({"example": "Too small: expected string to have >=1 characters"}),
+    },
+).openapi("ValidationErrorItem")
+
+
+class ValidationProblemFields(z.StrictObject):
+    type = z.literal("/problems/validation-error")
+    title = z.literal("Unprocessable Content")
+    status = z.literal(422)
+    detail = z.string()
+    instance = z.string().openapi({"description": "The request path"})
+    errors = z.array(ValidationErrorItem)
+
+
+ValidationProblem = ValidationProblemFields.openapi(
+    "ValidationProblem",
+    {"description": "RFC 9457 Problem Details for a request part that does not match its schema."},
+)
+
+__all__ = ["ValidationErrorItem", "ValidationProblem"]

zopy_takibiapi-0.1.0/python/zopy_takibiapi/schemas.py

@@ -0,0 +1,187 @@
+"""``ZopySchemas``: zopy (Zod for Python) schemas as takibi's schemas (see ``takibiapi.schemas``).
+
+Requests are parsed with the route's schemas exactly as Zod parses: checks included, no
+conversion unless the schema asks for it (``z.coerce.number()`` for a numeric path parameter), and
+no unknown keys (every object must be ``z.StrictObject``). Responses are encoded with the schema
+the route declares for the status (``safeEncode``: checked, and codecs turned into their wire
+form) before they are written. As in Zod, ``.openapi("Todo")`` names a schema: it is written once to
+``components.schemas`` and referenced with ``$ref``; other schemas are written in place.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator, Mapping
+from typing import Any, Literal
+
+from zopy import z
+from zopy.core import ZodType
+from zopy.declarative import Object, ObjectMeta
+from zopy.registries import globalRegistry, openapiParamRegistry
+
+from takibiapi import ValidationError
+from takibiapi.schema import dumps, loads
+
+from .problems import ValidationProblem
+
+COMPONENT_URI = "#/components/schemas/{}"
+
+
+def is_schema(tp: Any) -> bool:
+    return isinstance(tp, (ZodType, ObjectMeta))
+
+
+def _children(value: Any) -> Iterator[Any]:
+    """The schemas directly inside ``value``'s definition (object fields, array items, ...)."""
+    if isinstance(value, ObjectMeta):
+        yield from value.shape.values()
+    for item in value._def.values():
+        if is_schema(item):
+            yield item
+        elif isinstance(item, (list, tuple)):
+            yield from (i for i in item if is_schema(i))
+        elif isinstance(item, Mapping):
+            yield from (i for i in item.values() if is_schema(i))
+
+
+def strict_error(schema: Any) -> str | None:
+    """Why ``schema`` is not strict enough, or None: every object must reject unknown keys."""
+    seen: set[int] = set()
+    stack = [schema]
+    while stack:
+        current = stack.pop()
+        if id(current) in seen:
+            continue
+        seen.add(id(current))
+        definition = current._def
+        if definition.get("type") == "object" and not isinstance(definition.get("catchall"), z.ZodNever):
+            name = current.__name__ if isinstance(current, type) else type(current).__name__
+            return f"{name} is not strict: unknown keys must be an error (subclass z.StrictObject)"
+        stack.extend(_children(current))
+    return None
+
+
+def _checked(tp: Any, target: str) -> Any:
+    if not is_schema(tp):
+        raise TypeError(f"request {target} / response schemas must be zopy schemas, got {tp!r}")
+    error = strict_error(tp)
+    if error is not None:
+        raise TypeError(error)
+    return tp
+
+
+def _issues(error: Any) -> list[dict[str, Any]]:
+    return [{"path": list(i["path"]), "code": i["code"], "message": i["message"]} for i in error.issues]
+
+
+def _unwrapped(schema: Any) -> Any:
+    """The schema inside ``.optional()`` / ``.nullable()`` / ``.default()``."""
+    while not isinstance(schema, ObjectMeta) and "innerType" in schema._def:
+        schema = schema._def["innerType"]
+    return schema
+
+
+class _Checker:
+    __slots__ = ("_schema", "names")
+
+    def __init__(self, tp: Any, target: str) -> None:
+        self._schema = _checked(tp, target)
+        if target == "json":
+            self.names: list[tuple[str, bool]] = []
+            return
+        if not isinstance(tp, ObjectMeta):
+            raise TypeError(f"request {target} parts must be an object schema (z.StrictObject), got {tp!r}")
+        self.names = [(name, isinstance(_unwrapped(field), z.ZodArray)) for name, field in tp.shape.items()]
+
+    def decode(self, value: Any, *, coerce: bool) -> Any:
+        # Parameters arrive as text and are parsed as the schema says (z.coerce converts), as in Zod.
+        result = self._schema.safeParse(value)
+        if not result.success:
+            raise ValidationError(_issues(result.error))
+        return result.data
+
+    def decode_json(self, data: bytes) -> Any:
+        return self.decode(loads(data), coerce=False)  # loads raises ValueError for malformed JSON
+
+
+def _wire(value: Any) -> Any:
+    """``dumps``'s ``default`` for an encoded result: a z.Object instance as its wire dict (the
+    JSON writer then writes its values, calling this again for nested objects)."""
+    if isinstance(value, Object):
+        # Without optional fields to leave out, the instance's own dict is the wire dict.
+        return value._wire_dict() if type(value)._absent_when_none() else vars(value)
+    raise TypeError(f"Object of type {type(value).__name__} is not JSON serializable")
+
+
+class _Encoder:
+    __slots__ = ("_schema",)
+
+    def __init__(self, tp: Any) -> None:
+        self._schema = _checked(tp, "response")
+
+    def encode_json(self, value: Any) -> bytes:
+        result = self._schema.safeEncode(value)
+        if not result.success:
+            raise ValidationError(_issues(result.error))
+        return dumps(result.data, default=_wire)
+
+
+class _DocBuilder:
+    """Schemas as zopy's ``toJSONSchema`` writes them, named ones (``.openapi("Todo")``) collected
+    into ``components``. Bodies are documented in their wire form (``io: "input"``, a codec's JSON
+    side) both ways: requests are parsed from it and responses encoded into it."""
+
+    def __init__(self, openapi31: bool) -> None:
+        self.openapi31 = openapi31
+        self.components: dict[str, Any] = {}
+
+    def of(self, tp: Any, io: Literal["input", "output"] = "input") -> dict[str, Any]:
+        params = {
+            "target": "draft-2020-12" if self.openapi31 else "openapi-3.0",
+            "io": "input",
+            "unrepresentable": "any",
+            "uri": COMPONENT_URI.format,
+        }
+        out = z.toJSONSchema(tp, params)
+        out.pop("$schema", None)
+        for key in ("$defs", "definitions"):
+            for name, schema in out.pop(key, {}).items():
+                known = self.components.setdefault(name, schema)
+                if known != schema:
+                    raise TypeError(f"two different schemas are named {name!r} (.openapi({name!r}))")
+        return out
+
+    def parameters(self, tp: Any, location: str) -> list[dict[str, Any]]:
+        if not isinstance(tp, ObjectMeta):
+            raise TypeError(f"{location} parameters must be an object schema, got {tp!r}")
+        out: list[dict[str, Any]] = []
+        for name, field in tp.shape.items():
+            param: dict[str, Any] = {
+                "name": name,
+                "in": location,
+                "required": location == "path" or not field.isOptional(),
+                "schema": self.of(field),
+            }
+            meta = globalRegistry.get(field) or {}
+            if "description" in meta:
+                param["description"] = meta["description"]
+            param.update(openapiParamRegistry.get(field) or {})
+            out.append(param)
+        return out
+
+
+class ZopySchemas:
+    """zopy schemas as takibi's schemas: request and response checks, Zod's semantics."""
+
+    validation_problem: Any = ValidationProblem
+
+    def checker(self, tp: Any, target: str) -> _Checker:
+        return _Checker(tp, target)
+
+    def response_encoder(self, tp: Any) -> _Encoder:
+        return _Encoder(tp)
+
+    def builder(self, openapi31: bool) -> _DocBuilder:
+        return _DocBuilder(openapi31)
+
+
+__all__ = ["ZopySchemas", "is_schema", "strict_error"]