Models
An adorm model is a pydantic BaseModel subclass of adorm.Model. The class describes a database row for adorm and a pydantic schema. It declares its fields, its identity (_meta) and its relations.
import decimal
from adorm import ForeignKey, Model, ModelMeta
class Club(Model):
_meta = ModelMeta("club.Club")
id: int | None = None
name: str
class Member(Model):
_meta = ModelMeta("club.Member")
id: int | None = None
name: str
fee: decimal.Decimal = decimal.Decimal("10")
active: bool = True
club_id: int | None = None
club = ForeignKey("club.Club")Generated models
For a schema that Django owns, adorm generate writes one module per Django app, with the same labels, field names and relations as the Django models, and checks in CI that the modules are up to date.
adorm generate --settings myproject.settings --output myproject/adorm_models clubs billing libraryA generated model is an ordinary adorm model with the hash of the Django model's schema in _meta.schema_hash, which a driver compares with its own model's at use (schema checks). A field whose name clashes with pydantic (json, copy, model_dump …) gets a _ suffix and an alias with the original name: code and queries use json_, JSON and the JSON schema use json.
from myproject.adorm_models.library import Note
note = await Note.objects.get(json_="{}")
note.json_ # "{}"
note.model_dump()["json"] # "{}"Bound models
Model.objects returns the model bound to the current session; its query methods build query sets that run on that session:
member = await Member.objects.get(pk=1)
active = [m async for m in Member.objects.filter(active=True)]objects is a class attribute, not a field; instances and abstract models do not have it. It is the model's default manager. A model declares other managers, and methods of its managers and query sets, the same way.
Model identity
_meta names the model by its label ("app_label.ModelName"), which operations and drivers use, and names the primary key field ("id" unless given). A class with _meta registers in adorm.models.registry, which finds model classes by label and gives the operation encoding the type of every field.
from adorm.models import registry
registry.get("club.Member") # Member
registry.model_schema("club.Member").fields["fee"] # decimal.DecimalInstances from rows
from_row() builds an instance from a database row with pydantic's model_construct(), without validation. The fields the row contained are the instance's model_fields_set.
member = Member.from_row({"id": 1, "name": "Ana", "fee": decimal.Decimal(12), "club_id": 7})Instances built by the application go through pydantic validation as usual:
member = Member(name="Ana", fee="12.50") # fee == Decimal("12.50")
Member(name="Ana", fee="abc") # pydantic.ValidationErrorDeferred fields
A query with only() or defer() loads some fields; the others are deferred. Reading a deferred field raises AttributeError; adorm never loads a field implicitly. Assigning a deferred field sets it.
member = Member.from_row({"id": 1, "name": "Ana"}) # e.g. from .only("name")
member.name # "Ana"
member.fee # AttributeError: Member.fee is deferred
member.get_deferred_fields() # {"fee", "active", "club_id"}Annotations and other extra values
Names that are neither fields nor relations are pydantic extra values (extra="allow"): annotations from a query, the to_attr of a prefetch, or attributes the application sets. They are dumped with the fields and never saved. An extra value cannot take the name of a class attribute such as save or pk.
member = Member.from_row({"id": 1, "name": "Ana", "payments_total": decimal.Decimal(30)})
member.payments_total # Decimal("30")Relations
A relation is a descriptor, not a field: it is not validated, not dumped and not in the JSON schema. Reading a ForeignKey returns an awaitable.
club = await member.club # loads the club, then caches it
club = await member.club # from the cache
member.club = other_club # sets member.club_id
member.club = None # clears member.club_idA row loaded with select_related("club") fills the cache; the first await runs no operation. After club_id changes, the next await loads the new club.
A ReverseOneToOne (the other side of a one-to-one foreign key) returns an awaitable too; no related row raises the target's DoesNotExist:
restaurant = await place.restaurantA ReverseForeignKey (the other side of a foreign key) and a ManyToMany return a QuerySet of the related rows on the owner's session, from the target model's objects manager (related rows). Building it needs no connection; its operations run in that session's transaction.
club.members.query # Query("club.Member").filter(club_id=club.pk)
activity.tags.query # Query("club.Tag").filter(pk__in=<link rows of the activity>)
async for member in club.members.filter(active=True):
...In Python input a relation name stands for its column: Member(name="Ana", club=club) sets club_id and caches club. JSON input carries the column ("club_id": 7); a relation name in it is a validation error.
After prefetch_related() the relations hold the prefetched objects: an await of a foreign key runs no operation, and the query set of a reverse or many-to-many relation reads the prefetched rows for async for, count() and exists().
Generic foreign keys
A GenericForeignKey points at a row of any model: the content type field (a foreign key to Django's ContentType) names the model, the object id field holds the row's primary key. adorm generate writes one for every Django GenericForeignKey. Awaiting it loads the row of the registered adorm model for the content type; the object is cached while both fields keep their values. A missing row gives None, as in Django.
class InvoiceLine(Model):
_meta = ModelMeta("billing.InvoiceLine")
id: int | None = None
content_type_id: int
object_id: int
content_type = ForeignKey("contenttypes.ContentType")
item = GenericForeignKey()
line = await InvoiceLine.objects.first()
item = await line.item # a Membership or an Activity
line.item = None # clears content_type_id and object_id
line.item = activity # object_id = activity.pk; content_type_id when it is cached
await line.save() # reads Activity's content type id first when it is not
line = await InvoiceLine.objects.create(invoice_id=1, item=membership, description="Fee", unit_price=120)Assigning an instance sets the object id at once. The next save(), full_clean(), create() or bulk_create() reads the content type id through adorm.content_types on the session that writes, from the cache when it is there. Until then content_type_id holds the id cached for the instance's session; when none is cached it is unset, reading it raises AttributeError and model_dump() leaves it out. get_or_create() and update_or_create() take an instance in defaults too. Details are in the reference. Query paths do not traverse a generic foreign key.
Content types
adorm.content_types is adorm's ContentType.objects.get_for_model(): the content type id of a model, read once per database and cached, and the model of a content type id:
from adorm import content_types
location_type = await content_types.get_id(Location) # a Get the first time, then from the cache
links = TaggedItem.objects.filter(content_type_id=location_type, object_id__in=ids)
await content_types.get_model(location_type) # Location
row = await content_types.get_for_model(Location) # an instance of the generated ContentType model
await content_types.get_id(LocationProxy) # Location's id: a proxy uses its concrete model'sA lookup inside a transaction reads on the transaction's slot. Django's migrate creates the rows, adorm does not; a model without a row raises ContentType.DoesNotExist. migrate and flush (after each TransactionTestCase test) create the rows again, and the Django and asyncpg drivers clear the cache on Django's post_migrate signal; content_types.clear() clears it otherwise.
Multi-table inheritance
A child model of multi-table inheritance derives from its parent's adorm model, with its own label and a primary key that is the parent link (activity_ptr_id). Reading and saving a child reads and writes the rows of both tables. create_from_parent() adds the child's row to a parent row that exists, leaving the parent's row as it is:
crag = await Activity.objects.get(name="Crag day")
competition = await Competition.objects.create_from_parent(crag, discipline="Climbing")
competition.capacity # 15, the parent's valueEquality
Instances are equal when they are rows of the same model with the same primary key, whatever their other values, as in Django. Instances without a primary key are equal only to themselves and cannot be put in a set.
Member.from_row({"id": 1, "name": "Ana"}) == Member.from_row({"id": 1, "name": "Bea"}) # TrueSaving
await instance.save() writes the fields in model_fields_set: the fields the row was loaded with and the fields assigned since; deferred fields are not written, as in Django. For a new instance it writes the fields given to the constructor or assigned; the target fills in the rest with its defaults.
member = Member(name="Ana")
await member.save() # inserts name; id comes back from the database
member.active = False
await member.save(update_fields=["active"]) # updates one columnsave() builds a Save operation and runs it on the instance's executor: the session of the query set that loaded the instance, or else the current session. See the Model API for every option and error.
Creating many instances
bulk_create() inserts new instances with one operation. Each instance writes the fields save() would write; the target fills in the rest with its defaults. The instances come back with the values the database set, primary keys included, and are stored instances. As in Django, no save() override runs, no signal fires, and a multi-table inheritance child cannot be inserted this way.
clubs = await Club.objects.bulk_create(Club(name=name) for name in ("Koper", "Piran", "Izola"))
[club.pk for club in clubs] # [7, 8, 9]
clubs[0].name = "Koper Sailing"
await clubs[0].save() # an UPDATE: the instance is stored
# 10 000 rows, 1 000 per INSERT; one transaction, so a failing row stores none of them.
await Member.objects.bulk_create(members, batch_size=1000)
# Rows whose primary key exists are skipped; with update_conflicts they update the stored row instead.
await Member.objects.bulk_create(members, ignore_conflicts=True)
await Member.objects.bulk_create(members, update_conflicts=True, update_fields=["fee"], unique_fields=["pk"])Under ignore_conflicts the database reports no primary keys, so the instances keep None for a generated one.
Validating
Pydantic validates the values given to the constructor. await instance.full_clean() validates the instance as the target does before a save: on the Django driver Django's Model.full_clean() runs the field validators, the model's clean(), the unique checks and the constraints, against the database in the current transaction. Errors raise adorm.ValidationError with the errors by adorm field name, each with Django's message, code and params; exclude leaves fields out:
invoice.due = datetime.date(2025, 1, 1)
try:
await invoice.full_clean()
except adorm.ValidationError as exc:
exc.message_dict # {"due": ["The due date cannot be before the issue date."]}
[error] = exc.error_dict["due"]
error.code # None: clean() raised the error without a code
await invoice.full_clean(exclude=["due"])
club.name = "x" * 101
try:
await club.full_clean()
except adorm.ValidationError as exc:
[error] = exc.error_dict["name"]
error.code, error.params["limit_value"] # ("max_length", 100)A model's save() that calls full_clean() raises the same errors from save() and objects.create() on the Django driver.
See full_clean() in the Model API for the instance it validates and the error keys.
Deleting
await instance.delete() deletes the instance's row and the rows that cascade from it, and returns (total, {label: count}). When rows were deleted, the instance's primary key becomes None. On the Django driver the Django model's own delete() runs, so an override (a soft delete) applies; the native PostgreSQL driver refuses the delete of a model with an override.
total, per_model = await member.delete() # (3, {"clubs.Member": 1, "clubs.Membership": 2}); member.pk is NoneA PROTECT or RESTRICT reference forbids the delete: it raises ProtectedError or RestrictedError with the referencing objects as instances of the registered models, and the instance keeps its primary key. See delete() in the Model API.