pre-alpha

3.5 · Guides

Schemas derived from models

Each example below includes its own imports. Post is the blog example's model (examples/blog/models.py).

A Schema can take its fields and constraints from a Model. Pass the source model to the single @derive(Model, ...) decorator when selecting or making fields optional. A class without a decorator can still use model=Model to derive every column during the compatibility cycle.

from blog.models import Post
from hinoki import Schema, derive


@derive(Post, only=("title", "slug", "body"))
class PostCreate(Schema): ...


@derive(Post, exclude=("author_id",))
class PostOut(Schema):
    author_name: str


@derive(Post, only=("title", "body"), partial=True)
class PostPatch(Schema): ...


@derive(Post)
class PostAll(Schema): ...
Option Effect
@derive(Post, ...) source model and field selection
only=("a", "b") take exactly these columns
exclude=("a",) take every column except these
partial=True make every selected derived field optional (UNSET when absent)
partial=("a",) make only the named selected fields optional

only and exclude cannot be combined. An empty only=() is invalid; exclude=() is equivalent to selecting all columns. Model field types, maximum lengths, defaults and nullability are used. Annotations in the class body add fields or override a derived field, and methods and checks in the body are kept. Methods can use zero-argument super() as usual.

Unknown columns, a non-model, an empty only, optional names outside the selection, a class that is not a Schema, or a second @derive on the same class fail when the class is declared. Relations are not derived as nested values; declare the API shape explicitly. Model derivation includes all columns by default, so use only or exclude when the API must omit private fields. During the compatibility cycle, @derive(options...) with model=Model remains valid and emits DeprecationWarning; use @derive(Model, options...) for new code.

Inheriting from a Schema

A derived class inherits its base's fields as usual, and only or exclude cannot remove an inherited field. To fail closed, a derivation whose selection leaves out a model column that a base Schema already declares raises RegistrationError when the class is declared, naming the field and the base:

from blog.models import Post
from hinoki import Schema, derive


@derive(Post)
class PostAll(Schema): ...


@derive(Post, only=("title",))  # RegistrationError: inherited field 'id' from PostAll
class TitleOnly(PostAll): ...

Derive the narrower Schema from Schema (or from a base that declares only the columns it keeps). A selection that keeps or widens the inherited columns is allowed, and a field redeclared in the class body is kept on purpose.

Return a Model from a Schema-annotated handler

When a handler declares one concrete response Schema, Hinoki converts a directly returned Model with that Schema's from_model() projection:

from uuid import UUID

from blog.models import Post
from hinoki import Schema, derive, http


@derive(Post, only=("id", "title"))
class PostSummary(Schema): ...


@http.get("/posts/{post_id}")
async def one(post_id: UUID) -> PostSummary:
    return await Post.aget(id=post_id)  # type: ignore[return-value]

The declared Schema decides what is sent for these results:

Handler result Response body
an instance of the declared Schema sent as is
an instance of a subclass of the declared Schema only the declared Schema's fields; the subclass's extra fields are dropped
one Model row from_model() projection of that row
a Model row that fails the Schema's constraints 500 internal_error with the request id; the ValidationError is logged as the cause and not sent to the client
a Model of another class than the Schema's source model 500 internal_error
a list or Page of Model rows 500 internal_error; convert explicitly with from_models()
a dict or other plain value 500 internal_error; sent unchanged only with validate_response=False

Plain values are checked

A returned dict (or any other non-Schema, non-Model value) where the annotation names a Schema is a 500 internal_error: the annotation is enforced at runtime (see the response check). Return a Schema instance or a Model; declare the action with validate_response=False only to send a value as it is.

A row that fails the Schema's constraints is the server's fault (for example a stored value longer than the Schema allows), so it is never reported as a client 422. No relation is loaded implicitly. For a computed field such as author_name, keep using PostOut.from_model(post, author_name=...).

Static type checkers do not know about this runtime conversion: they see a Post returned from a function annotated -> PostSummary as a type error. This is a limitation of static typing, not of the handler, so the intentional Model return needs # type: ignore[return-value] (or an explicit PostSummary.from_model(...) call, which type-checks without one). Derived fields are also not synthesized for static type checkers, so declare fields in the Schema body when they need static checking.

Add validation checks

Use @field_check("name") for a rule on one or more structurally valid fields, and @object_check for a rule over the whole object. Raise Invalid(code, message, path=...) to report a problem. Checks are synchronous and must not perform I/O; database-dependent rules belong in an operation.

from typing import Annotated

from hinoki import Field, Invalid, Schema, field_check, object_check


class SignUp(Schema):
    username: Annotated[str, Field(min_length=3, max_length=32)]
    password: Annotated[str, Field(min_length=12)]
    confirmation: str

    @field_check("username")
    def username_characters(self, value: str) -> None:
        if not value.replace("_", "").isalnum():
            raise Invalid("username_characters", "use letters, numbers and _ only")

    @field_check("password")
    def reject_common_password(self, value: str) -> None:
        if value.lower() in {"password12345", "qwerty123456"}:
            raise Invalid("common_password", "choose a less common password")

    @object_check
    def passwords_match(self) -> None:
        if self.password != self.confirmation:
            raise Invalid("mismatch", "passwords do not match", path="confirmation")

Structural errors are reported before custom checks. All applicable check failures are returned together. See schemas for the validation contract and conversion methods.