3.6 · Guides
Model options¶
Options that describe a model beyond its columns are decorators, read like the action decorators. Hinoki has no nested class Meta. Only what is needed when the class is created stays a class keyword.
from datetime import datetime
from uuid import UUID, uuid4
from hinoki import db
from hinoki.orm import Model, OnDelete, field, foreign_key, timestamps, unique
from hinoki.utils import utc_now
class Member(Model):
id: UUID = field(primary_key=True, default_factory=uuid4)
@unique("owner_id", "url")
@db.indexed("owner_id", "created_at")
@db.ordered_by("-created_at", "-id")
@timestamps()
@db.table("saved_links")
class Bookmark(Model, label="Saved link", plural="Saved links"):
id: UUID = field(primary_key=True, default_factory=uuid4)
owner_id: UUID = foreign_key(
Member, on_delete=OnDelete.RESTRICT, related_name="bookmarks"
)
url: str = field(max_length=500)
created_at: datetime = field(default_factory=utc_now)
updated_at: datetime = field(default_factory=utc_now)
| Option | Form | Effect |
|---|---|---|
| table | @db.table("saved_links") or table="saved_links" (optional) |
overrides the default <app>_<models> table name derived from the class and its module; the two forms may be combined only with the same name |
| app | app="billing" (optional class keyword) |
replaces the app part of the derived <app>_<models> table name; ignored when the table is named explicitly |
| labels | label=, plural= (optional class keywords) |
override the humanized singular and plural display names derived from the class |
| composite uniqueness | @unique("a", "b") |
a UNIQUE (a, b) constraint; a single column uses field(unique=True) |
| index | field(index=True) for one column; @db.indexed("a", "b") for one or more columns |
a CREATE INDEX planned by the migration tool; adding or removing one is a non-destructive migration |
| default order | @db.ordered_by("-created_at", "id") |
every query without order_by (lists, pages) is ordered this way; "-" is descending; an explicit order_by replaces it, counts and bulk updates ignore it |
| update timestamp | @timestamps() |
refresh a declared updated_at: datetime field for every ORM update statement; use @timestamps("modified_at", clock=...) to customize |
pk(default_factory=...)is a shorthand for a primary key field; it requires an explicit default or factory for static constructor typing. Existingfield(primary_key=True, ...)remains valid.db.table,db.indexedanddb.ordered_byare the same decorators ashinoki.orm.table,indexedandordered_by; import them from either place. Naming the table twice with different names (two@db.tabledecorators, or one andtable=) is an error that names both.field(index=...)takesTrueorFalse; other values are refused. A primary key or unique field already has an index;field(index=True)cannot be combined with either. Declaring the same one-column index throughfield(index=True)and@db.indexed("column")produces one index.- Column names are checked when the decorator is applied; a typo fails at import with the model and the unknown names.
- Stacked decorators are stored in reading order (top to bottom).
- A model inherits the options of its abstract bases. A decorator on the subclass replaces everything inherited for that kind of option (
@db.indexedreplaces the inherited indexes, and so on) and leaves the other kinds inherited. Afield(index=True)index stays with its column: it is inherited while the column keepsindex=True, and dropped when the subclass redeclares the column without it. A model that subclasses a table model does not inherit that parent's options. - Apply options before the model is used: the migration planner, the query layer and the admin read them from the class.
- The fallback table/display names use a small deterministic English suffix rule, not an inflector. Use explicit values for irregular, already-plural or localized names. Pin the table name with
@db.table(...)ortable=when a class has an existing migration history; changing an implicit name is a guarded drop/create, not a table rename. - Index names are
ix_<table>_<columns>_<digest>. The digest covers the table and each column name with its length, soindexed("a_b")andindexed("a", "b")never collide; the readable part is cut to the backend's identifier limit (63 bytes on PostgreSQL, 64 on MySQL and MariaDB).
Not yet: partial or expression indexes and soft delete. For timestamps, see utilities; fields are declared explicitly and migrations remain visible.