GuidesData
Schemas from models¶
A Schema can take its fields and constraints from a Model with
@derive(Model, ...). Response handlers convert rows explicitly with
from_model.
# notes/apps/billing/schemas.py
from hinoki import Schema, derive
from .models import Invoice
@derive(Invoice, only=("reference",))
class InvoiceIn(Schema): ...
@derive(Invoice, exclude=("customer_id",))
class InvoiceOut(Schema):
customer_name: str
@derive(Invoice, only=("reference", "paid"), partial=True)
class InvoicePatch(Schema): ...
@derive(Invoice)
class InvoiceRow(Schema): ...
| Option | Effect |
|---|---|
@derive(Invoice) |
every column |
only=("a", "b") |
exactly these columns |
exclude=("a",) |
every column except these |
partial=True |
every selected field optional (UNSET when absent) |
partial=("a",) |
only the named fields optional |
Column types, maximum lengths, defaults and nullability carry over. Annotations
in the class body add or override fields; methods and checks are kept.
Relations are not derived: declare nested shapes explicitly. Derivation takes
every column by default, so use only or exclude when a column is private.
These fail when the class is declared, with RegistrationError: unknown
columns, a non-model, only together with exclude, an empty only=(),
partial names outside the selection, a class that is not a Schema, and a
second @derive. (exclude=() selects every column.) The older model= class
keyword (class InvoiceOut(Schema, model=Invoice)) still derives every
column; prefer @derive(Invoice). Combining it with @derive(...) without a
model emits DeprecationWarning.
Inherit from a derived schema¶
A subclass inherits its base's fields; only and exclude cannot remove them.
A derivation that would leave out a column the base declares fails closed:
@derive(Invoice, only=("reference",)) # RegistrationError: inherited field 'id'
class ReferenceOnly(InvoiceRow): ...
Derive the narrower schema from Schema instead. A selection that keeps or
widens the inherited columns is allowed.
Convert rows¶
Return a Schema, never a Model:
# notes/apps/billing/api.py
from uuid import UUID
from hinoki import RouteGroup, errors
from hinoki.pagination import Page, PageNumberPagination, PageParams
from notes.security import billing_staff
from .models import Invoice
from .schemas import InvoiceOut
invoices = RouteGroup("/invoices", access=billing_staff)
def to_out(invoice: Invoice) -> InvoiceOut:
return InvoiceOut.from_model(invoice, customer_name=invoice.customer.name)
@invoices.get("/", pagination=PageNumberPagination())
async def list_invoices(page: PageParams) -> Page[InvoiceOut]:
rows = await Invoice.all().select_related("customer").apaginate(page)
return rows.map(to_out)
@invoices.get("/{invoice_id}", errors=(errors.NotFound,))
async def get_invoice(invoice_id: UUID) -> InvoiceOut:
invoice = await Invoice.filter(id=invoice_id).select_related("customer").aget()
return to_out(invoice)
from_model(row, **extra)reads the attributes the schema needs;extrafills fields the model lacks, such ascustomer_name. A missing attribute raisesAttributeError.from_models(rows, **extra)converts a list;extrais shared by every row. For a page,Page.map(InvoiceOut.from_model).- Relations must be loaded first (
select_related); nothing is fetched lazily. - An invalid stored value (longer than the schema allows) is the server's
fault: it becomes
500 internal_error, logged with theValidationError, never a client 422.
Returning a model
A handler annotated with one concrete Schema still converts a single
returned Model of the derived class at runtime, but type checkers reject
it and the HNK-API-001 rule (Actions.forbid_model_responses) reports
it. Lists or pages of models, models of another class, and plain dict
values are 500 internal_error unless the action sets
validate_response=False. A subclass instance is sent with the declared
fields only. See the response check.
See also¶
- Schemas
- Validate input
- Generate CRUD routes:
read=,create=andupdate=take these schemas