Model API
The model base class, model identity, relation descriptors, managers and the model registry, importable from adorm.models. Model, ModelMeta, Manager, driver_method, the relation descriptors ForeignKey, ReverseForeignKey, ReverseOneToOne, ManyToMany and GenericForeignKey, and the content type cache content_types (ContentTypes) are also importable from adorm.
from adorm import driver_method, ForeignKey, Manager, Model, ModelMeta, ReverseOneToOne
from adorm.models import get_managers, get_relations, model_schema, registry, set_executor_resolverThe examples on this page use these models:
import datetime
import decimal
from pydantic import Field
from adorm import ForeignKey, Model, ModelMeta
class Club(Model):
_meta = ModelMeta("club.Club")
id: int | None = None
name: str
founded: datetime.date | None = None
class Member(Model):
_meta = ModelMeta("club.Member")
id: int | None = None
name: str
fee: decimal.Decimal = decimal.Decimal("10")
active: bool = True
json_: str | None = Field(default=None, alias="json")
club_id: int | None = None
club = ForeignKey("club.Club")Models
adorm.Model
Base class of adorm models, a subclass of pydantic BaseModel. A model declares _meta (a ModelMeta), its fields as pydantic fields and its relations as Relation descriptors. A subclass without its own _meta inherits its parent's; a model without any _meta is abstract: it cannot load or save rows and its instances compare by identity.
The model configuration:
| Setting | Value | Effect |
|---|---|---|
extra | "allow" | names that are neither fields nor relations (annotations, the to_attr of a prefetch) are extra values |
ignored_types | (Relation, <the objects descriptor>) | relations and objects are class attributes, absent from validation, serialisation and the JSON schema |
serialize_by_alias | True | a field with an alias is dumped under the alias |
validate_by_name, validate_by_alias | True | input may use the field name or the alias |
protected_namespaces | () | field names may start with model_ (a name equal to a pydantic attribute still raises) |
Input (the constructor, model_validate()) also accepts:
pkfor the primary key field:Club(pk=5, name="Chess")setsid. Giving bothpkand the field is aValidationError.- A relation name, from Python input only; see
ForeignKey.
An extra value may not have the name of a class attribute (save, pk, model_config …), which would hide it: such input is a ValidationError.
A field whose name clashes with a pydantic method (model_dump, json …) has a _ suffix and the original name as its alias: code and queries use json_, JSON and the schema use json.
member = Member.model_validate({"name": "Ana", "json": "{}"})
member.json_ # "{}"
member.model_dump()["json"] # "{}"
"club" in Member.model_json_schema()["properties"] # FalseClass creation raises TypeError when _meta is not a ModelMeta or is declared as a private attribute (_meta: ModelMeta = ...; annotate it ClassVar[ModelMeta] or leave it unannotated), when the primary key named by _meta is not a field, and when a ForeignKey column is not a field. A model with _meta in its own class body registers in registry.
Every model class has its own DoesNotExist and MultipleObjectsReturned, derived from its parents' and at the top from ObjectDoesNotExist and MultipleObjectsReturned.
from_row(row, *, executor=None)
Class method: an instance of a stored row, built with model_construct() (no validation). row maps field names or aliases to values; pk stands for the primary key field.
- A field missing from
rowis deferred. - A key that is a relation name holds the related row: a mapping (built with the related model's
from_row()), an instance of the target (TypeErrorfor another model), orNonefor no related row. It fills the relation's cache, asselect_related()does. - Any other key is an extra value. A key that names a class attribute raises
ValueError, as do bothpkand the primary key field.
executor runs the instance's later operations (save(), relation loads) and those of the related instances built from row. The row must contain the primary key (ValueError); an abstract model raises TypeError.
member = Member.from_row({"id": 1, "name": "Ana", "club_id": 7, "visits": 3})
member.model_fields_set # {"id", "name", "club_id"}
member.visits # 3, an extra value
member.fee # AttributeError: Member.fee is deferredDeferred fields
A field the row did not load (a query with only() or defer()) is deferred. Reading it raises AttributeError, so hasattr() and getattr(obj, name, default) treat it as missing. Assigning it sets it and adds it to model_fields_set. model_dump() and repr() leave deferred fields out.
member = Member.from_row({"id": 1, "name": "Ana"})
member.get_deferred_fields() # {"fee", "active", "json_", "club_id"}
member.fee = decimal.Decimal(12)
member.get_deferred_fields() # {"active", "json_", "club_id"}
member.model_dump() # {"id": 1, "name": "Ana", "fee": Decimal("12")}objects
Class attribute: the model's default Manager, Manager() unless the class declares its own. Reading it returns the model bound to the current session, a BoundModel, evaluated at every access. Reading it on an instance or on an abstract model raises AttributeError. A class that sets objects to something other than a manager raises TypeError.
await Member.objects.filter(active=True).count()
clubs = Club.objects # stays bound to the session current nowget_deferred_fields()
The names of the fields the instance was loaded without and that were not assigned since.
pk
The primary key value, read and written through the field _meta.pk names.
Equality and hash
Two instances are equal when they belong to the same model (the same _meta.label, so a subclass instance equals its model's instance) and have the same primary key value that is not None. Other field values do not take part. An instance without a primary key value equals only itself and is unhashable (TypeError). The hash is hash((label, pk)). Instances of an abstract model compare and hash by identity.
a = Member.from_row({"id": 1, "name": "Ana"})
b = Member.from_row({"id": 1, "name": "Bea"})
a == b # True
len({a, b}) # 1
Member(name="Ana") == Member(name="Ana") # Falsesave(*, update_fields=None, force_insert=False, force_update=False)
Coroutine: write the instance with a Save operation on the instance's executor.
- The values written are the fields in
model_fields_set(the loaded and the assigned ones), the primary key excepted. Fields the instance never set are left to the target, so its defaults apply on insert. - Without a primary key value the row is inserted; with one it is updated, or inserted when no row has that key.
update_fieldslimits the update to those fields and never inserts. A relation name stands for its column, a generic foreign key's name for both of its fields, the primary key ("pk"or its field name) is ignored, and an emptyupdate_fieldssaves nothing. A named field the instance has but never set (a default) is written too.- A content type field of a pending
GenericForeignKeyassignment is resolved first, on the instance's executor. force_insertalways inserts;force_updatenever inserts.- The values the target returns (the primary key, database defaults) are set on the instance and added to
model_fields_set; the instance keeps the executor for later operations.
member = Member(name="Ana") # model_fields_set == {"name"}
await member.save() # Save("club.Member", None, {"name": "Ana"})
member.id # set from the result
member = Member.from_row({"id": 1, "name": "Ana"}, executor=executor) # loaded with only("name")
member.active = False
await member.save() # Save("club.Member", 1, {"name": "Ana", "active": False})
await member.save(update_fields=["active"])Raises TypeError for a string update_fields and a result that is not a mapping, ValueError for an update_fields name that is not a field, one that is deferred, and update_fields or force_update without a primary key value, and InterfaceError when no executor is available. A pending generic foreign key assignment whose model has no content type row raises the content type model's DoesNotExist (ObjectDoesNotExist when that model is not registered) before the Save operation. A failed or cancelled save leaves the instance unchanged, except for a content type field it resolved before the Save operation.
full_clean(*, exclude=None, validate_unique=True, validate_constraints=True)
Coroutine: validate the instance as the target validates one before a save, with a FullClean operation on the instance's executor. On the Django driver it is Django's Model.full_clean(): field validation (clean_fields()), the model's clean(), the unique checks (validate_unique()) and the model's constraints (validate_constraints()). Every query of the validation runs on the session's slot and the profile's database alias, regardless of the project's Django routers, and sees the session's open transaction.
- The instance validated is the one
save()would write: its loaded and assigned fields over the stored row for an instance with a primary key that is not_state.adding(the row is read when fields are missing), otherwise over the target's defaults. A unique check of a stored instance leaves its own row out. excludenames fields (or relations, for their column;"pk"for the primary key) that are not validated.validate_uniqueandvalidate_constraintsswitch the unique checks and the constraints off.- Errors raise
ValidationErrorwitherror_dict(andmessage_dict) by adorm name: a field's errors under the field name, a foreign key's under its relation's name ("club", not"club_id"), errors of the whole model (clean(), a constraint that is not a unique constraint over one field) under"__all__". - Each error keeps Django's
message,codeandparams:"blank","max_length"withlimit_valueandshow_value,"unique"(one field) or"unique_together"(several), a constraint'sviolation_error_code. The field names of theunique_checkparam are adorm names; a Django model instance or class inparams(model,model_class) is the model's label, a lazy translation is text. Messages are in the caller's active language; a plural message (Django'sngettext_lazy, as inmax_length) is formatted. - Without errors, the values the validation cleaned (Django's
to_python(), changesclean()made) are set on the instance's loaded fields; deferred fields stay deferred andmodel_fields_setdoes not change.
invoice = await Invoice.objects.get(number="2026-0001")
invoice.due = datetime.date(2025, 1, 1)
await invoice.full_clean()
# ValidationError({'due': ['The due date cannot be before the issue date.']})
copy = Membership(club_id=board.club_id, member_id=board.member_id, since=today, fee=1)
await copy.full_clean()
# ValidationError({'__all__': ['Membership with this Club and Member already exists.']})
await copy.full_clean(exclude=["member"]) # the constraint names an excluded field: no error
try:
await copy.full_clean()
except adorm.ValidationError as exc:
[error] = exc.error_dict["__all__"]
error.code # 'unique_together'
error.params["unique_check"] # ('club', 'member')Raises ValueError for an exclude name that is neither a field nor a relation, TypeError for a string exclude, and InterfaceError when no executor is available. A driver that does not declare full_clean raises NotSupportedError.
delete()
Coroutine: delete the instance's row and the rows that cascade from it with a DeleteInstance operation on the instance's executor, which runs the target's delete of one instance (on the Django driver the model's delete(), an override included; the native PostgreSQL driver raises NotSupportedError for a model with an override). Returns (total, {label: count}). When rows were deleted, the primary key is set to None; otherwise (a missing row, a delete() override that deletes nothing) the instance keeps it.
payment = await Payment.objects.get(reference="SI00 0001")
await payment.delete() # (1, {"billing.Payment": 1}); payment.pk is NoneRaises ValueError without a primary key value and InterfaceError when no executor is available. A reference that forbids the delete raises ProtectedError or RestrictedError with instances of the registered models as its objects, as QuerySet.delete() does; the instance keeps its primary key.
adorm.ModelMeta(label, pk="id", *, schema_hash=None, orm_names=None, concrete_model=None)
The identity of a model: its label ("app_label.ModelName") and the name of its primary key field. A frozen dataclass; an invalid label or pk name raises ValueError.
schema_hash: the hashadorm generatecomputed from the ORM model (adorm.codegen.compute_schema_hash),Nonefor a model written by hand. An empty or non-string value raisesValueError.orm_names: the target ORM's name of each field or relation whose Python name differs, by Python name;Noneis an empty mapping. A generated model fills it for the names it renames. A model class's_metaalso holds its model bases' entries for inherited fields and relations, so a multi-table inheritance child or a proxy maps an inherited name like its parent. It is stored read-only. A name that is not an identifier raisesValueError; anorm_namesentry that names no field or relation of the model class raisesTypeError.concrete_model: the label of the concrete model a proxy model stands for (Django'sconcrete_model),Nonefor a concrete model.adorm generatesets it on every proxy. The content type of a proxy is its concrete model's (natural_key()). An invalid label, or the model's own label, raisesValueError.orm_name(name): the ORM name of the field or relationname,nameitself whenorm_namesdoes not list it.
class Payment(Model):
_meta = ModelMeta("club.Payment", pk="code")
code: str | None = None
amount: decimal.Decimal
class Note(Model):
_meta = ModelMeta("club.Note", schema_hash="387e7a453a16eb5e", orm_names={"json_": "json"})
id: int | None = None
json_: str = Field(default="", alias="json")
Note._meta.orm_name("json_") # "json"
Note._meta.orm_name("id") # "id"
class SignedNote(Note):
_meta = ModelMeta("club.SignedNote", pk="note_ptr_id")
note_ptr_id: int | None = None
SignedNote._meta.orm_name("json_") # "json", inherited from Note
class PinnedNote(Note):
_meta = ModelMeta("club.PinnedNote", concrete_model="club.Note") # a proxy of Noteadorm.models.ModelState
Per-instance state outside the fields, the instance's private attribute _state:
| Attribute | Meaning |
|---|---|
adding | True until the instance is loaded or saved |
executor | the executor that loaded or last saved the instance, None otherwise |
related | cached related instances by relation name; the prefetched rows of a reverse or many-to-many relation; for a generic foreign key the content type, the object id and the instance they were loaded for |
generic | by generic foreign key name, the assigned instance whose content type the next write resolves, with the object id and the content type id set at assignment (None when it was not cached) |
A copy (copy.copy(), model_copy()) gets its own state with the same executor and a copy of the cache and the pending assignments; a deep copy deep-copies them. A pickled instance comes back without its executor.
Relations
adorm.models.Relation(target)
Base class of relation descriptors. target is the label of the related model, name the attribute name the descriptor is assigned to. target_model() returns the registered class of target (LookupError when none is registered). A relation is not a pydantic field: it is not validated, dumped or part of the JSON schema. A bare Relation names only the target: query paths traverse it (memberships__active), it has no join columns, and on an instance the attribute is the descriptor.
adorm.ForeignKey(target, *, column=None)
A many-to-one or one-to-one relation stored in the ordinary field column, by default <name>_id.
await instance.relreturns the related instance, orNonewhen the column isNone. The instance is loaded with aGetoperation (Query(target).filter(pk=column value)) on the owner's executor and cached on the owner. The cache serves while the cached instance's primary key equals the column;select_related()fills it.- A missing row raises the target's
DoesNotExist. - Assigning an instance of the target sets the column to its primary key and caches the instance; assigning
Noneclears both. Another model's instance raisesTypeError, an instance without a primary key valueValueError. - Reading the relation while the column is deferred raises
AttributeError. - On the class, the attribute is the descriptor.
class Member(Model):
_meta = ModelMeta("club.Member")
id: int | None = None
club_id: int | None = None
club = ForeignKey("club.Club")
sponsor_ref: int | None = None
sponsor = ForeignKey("club.Club", column="sponsor_ref")
club = await member.club # Get(Query("club.Club").filter(pk=member.club_id))
club is await member.club # True, from the cache
member.club = other_club # member.club_id == other_club.pk
member.club = None # member.club_id is None
Member.club.column # "club_id"A relation name in Python input (the constructor, model_validate()) sets the column before the fields are validated (a required column included) and caches the instance: Member(name="Ana", club=club) sets club_id. Its value is a saved instance of the target or None. Any other value, the relation together with its column, and a relation name in JSON input (model_validate_json()) raise ValidationError.
Member(name="Ana", club=club).club_id # club.pk
Member.model_validate_json('{"name": "Ana", "club": 5}') # ValidationError: give its column 'club_id'
Member.model_validate_json('{"name": "Ana", "club_id": 5}') # club_id == 5adorm.ReverseForeignKey(target, *, column)
The reverse side of a ForeignKey: the rows of target whose field column holds the owner's primary key. On an instance it returns those rows from the target's objects manager on the owner's executor (the session that loaded it, else the current session): a query set of the manager's queryset_class, starting from its get_queryset() and carrying its ORM manager. On an executor that is not a Session, the query set has that class and the ORM manager but no client-side get_queryset(). An instance without a primary key value and a column that is not an identifier raise ValueError.
class Club(Model):
_meta = ModelMeta("club.Club")
id: int | None = None
members = ReverseForeignKey("club.Member", column="club_id")
club.members.query # Query("club.Member").filter(club_id=club.pk), plus the manager's conditions
await club.members.count() # Count on the club's session
Club.members.column # "club_id"adorm.ReverseOneToOne(target, *, column)
The reverse side of a one-to-one ForeignKey: the row of target whose field column holds the owner's primary key (Django: the other side of a OneToOneField, also the parent's side of multi-table inheritance).
await instance.relreturns that row as an instance oftarget, loaded with aGetoperation (Query(target).filter(<column>=instance.pk)) on the owner's executor and cached on the owner.select_related()fills the cache.- No such row raises the target's
DoesNotExist, also whenselect_related()cached no row. - An instance without a primary key value and a
columnthat is not an identifier raiseValueError. On the class, the attribute is the descriptor.
class Place(Model):
_meta = ModelMeta("club.Place")
id: int | None = None
restaurant = ReverseOneToOne("club.Restaurant", column="place_id")
class Restaurant(Model):
_meta = ModelMeta("club.Restaurant", pk="place_id")
place_id: int | None = None
place = ForeignKey("club.Place")
restaurant = await place.restaurant # Get(Query("club.Restaurant").filter(place_id=place.pk))
restaurant is await place.restaurant # True, from the cacheadorm.ManyToMany(target, *, through, source_column, target_column)
A many-to-many relation through the model labelled through. Each through row links the owner in source_column with a target row in target_column. For a link table without a model of its own, through is the label of the ORM's generated through model (Django: "<app_label>.<Model>_<field>", e.g. "club.Activity_tags"). On an instance it returns the related rows from the target's objects manager on the owner's executor, as ReverseForeignKey does; an instance without a primary key value raises ValueError. A forward ForeignKey and a ReverseOneToOne load their row without the target's manager (Django's base manager).
class Activity(Model):
_meta = ModelMeta("club.Activity")
id: int | None = None
tags = ManyToMany("club.Tag", through="club.Activity_tags", source_column="activity_id", target_column="tag_id")
activity.tags.query
# Query("club.Tag").filter(
# pk__in=Query("club.Activity_tags").filter(activity_id=activity.pk).values("tag_id"))Prefetched rows
After prefetch_related() of a ReverseForeignKey or a ManyToMany, the query set the relation returns on the instance holds the prefetched rows: async for, count() and exists() read them without an operation. Its building methods (filter(), order_by() …) return query sets that run an operation, and its other terminal methods run one. A prefetched ForeignKey, ReverseOneToOne or GenericForeignKey fills the relation's cache; await instance.rel then runs no operation.
club = await Club.objects.prefetch_related("memberships").get(slug="koper-sailing")
[m.role async for m in club.memberships] # no operation
await club.memberships.count() # 3, no operation
await club.memberships.filter(active=True).count() # a Count operationadorm.GenericForeignKey(ct_field="content_type", fk_field="object_id", *, for_concrete_model=True)
A relation to a row of any model (Django's GenericForeignKey): the content type's primary key in the content type field and the row's primary key in the field fk_field. The content type field is the ForeignKey named ct_field, whose column and target are used, or a field <ct_field>_id holding a primary key of CONTENT_TYPE_MODEL. for_concrete_model (a bool, else TypeError) makes an assigned proxy instance store its concrete model's content type, as in Django.
await instance.relreturns the related instance. The content type id names the registered model throughcontent_types.get_model()(cached; a miss is aGetoperation), or through the content type relation's cache (select_related("content_type")); its row with the primary key infk_field(converted to the primary key's type,"7"to7) is loaded with aGetoperation on the owner's executor.- The instance is cached on the owner for the values of both fields it was loaded for and serves while the fields keep them. A field changed while a load or prefetch runs leaves the cache for the old values. A prefetch fills the cache.
- Either field
None, or no row with that primary key, givesNone. A content type of a model that is not registered raisesLookupError; reading the relation while either field is deferred raisesAttributeError. - It is not a
Relation: query paths do not traverse it, it is not part of the schema, andget_relations()leaves it out. A model class checks that both fields exist (TypeError).
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() # GenericForeignKey("content_type", "object_id")
item = await line.item # a Membership or an Activity
item is await line.item # True, from the cache
line.object_id = 7 # the next await loads again
lines = InvoiceLine.objects.prefetch_related("item") # one query per content typeAssignment
Assigning an instance, as an attribute or as a constructor keyword, points the relation at it:
fk_fieldgets the instance's primary key, validated as the field's type, orstr(pk)when the key itself does not validate (an integer key in a text field).- The content type is pending until the owner's next write:
save(),full_clean(),create()orbulk_create(). The write sets the content type field to the content type id of the instance's model (its concrete model's withfor_concrete_model), taken withcontent_types.get_id()on the executor that writes (the instance's forsave(), the query set's forcreate()), from the cache when cached. A row written through another session gets that database's id. - Until that write the content type field holds the id
content_typeshas cached for the owner's executor. When none is cached, the field is unset: reading it raisesAttributeError, andmodel_dump()andrepr()leave it out, as they do a deferred field.await instance.relgives the assigned instance without an operation. - No content type row for the assigned model makes the write raise the content type model's
DoesNotExist(ObjectDoesNotExistwhen that model is not registered); nothing is written. A write that fails or is cancelled while it resolves leaves the assignment pending and writes nothing. - An assignment that changes while a write resolves it (another instance or
Noneassigned, a field set, a concurrent write resolving it first) is resolved anew or left as it is; the write stores the current pair. - Assigning either field afterwards drops the pending content type.
- As an attribute: an instance without a primary key value or whose key fits
fk_fieldneither way raisesValueError, a value that is not an instance of a model with_metaTypeError;Nonesets both fields toNone. - As a constructor or
create()keyword, every refusal raises pydantic'sValidationError: a value that is not a stored model instance, the relation given together with either field, andNonefor a content type or object id field that is not nullable. JSON input (model_validate_json()) gives the two fields instead. get_or_create()andupdate_or_create()take the relation indefaultsandcreate_defaultsand write both fields; the content type id is taken on the query set's executor before the operation. The relation in their lookups raisesFieldError, as a query path.
line = await InvoiceLine.objects.create(invoice_id=1, item=membership, description="Fee", unit_price=120)
line.content_type_id # the id of clubs.Membership, read once and cached
line.item = activity # content_type_id readable at once when Activity's id is cached
await line.save() # a Get of the content type when it is not cached, then the Save
await line.save(update_fields=["item"]) # writes content_type_id and object_idMethods of the descriptor:
object_id(model, value): the valuefk_fieldofmodelholds for the instancevalue; raisesTypeErrorandValueErroras attribute assignment does.cached_content_type(model, executor, value): the content type id ofvalue's model ascontent_typeshas it cached forexecutor,Nonewhen it is not cached.assigned(instance): the instance whose content type the next write resolves,Nonewhen no assignment is pending.await resolve(instance, executor): sets the content type field of a pending assignment withcontent_types.get_id()onexecutor; nothing when no assignment is pending.
adorm.models.CONTENT_TYPE_MODEL
"contenttypes.ContentType": the content type model a GenericForeignKey reads when its content type field is not a ForeignKey of the model, and the default content_type_model of content_types.
Content types
A content type row (Django's ContentType) names a model by app_label and model, the lowercased class name; a generic foreign key stores its primary key. The target creates the rows (Django's migrate); adorm only reads them.
adorm.ContentTypes
Content type ids by model and models by content type id, cached per database: Django's ContentType.objects.get_for_model() and get_for_id(). Every method but clear() takes:
session: theSession(or another executor) whose database it reads, by default the current session. Inside a transaction of that session it reads on the transaction's slot, also from a task that inherits the context, so a lookup never waits for a second slot.content_type_model: the label of the content type model, by defaultCONTENT_TYPE_MODEL.for_concrete_model(where a model is given): a proxy model uses its concrete model's content type (natural_key()).
The cache key:
- the database the session's profile connects to, as its driver names it (
Driver.database_key()). Profiles whose drivers name the same database share the cache, such as per-user profiles that differ only in hooks or options. The Django and asyncpg drivers name the host, port and database name of the profile'sDATABASESentry with itsparamsapplied, and none for a profile with aconnecthook; - the profile, when its driver names no database: sessions of the profile share the cache, and a replaced or unregistered profile starts with an empty one;
- the profile's name, for a session whose profile is not registered;
- the executor object, for any other executor.
Each lookup that misses runs its own operation; concurrent lookups do not wait for one another, and a cancelled one leaves the others running. The Django and asyncpg drivers connect Django's post_migrate signal to clear(): migrate and flush (run by a TransactionTestCase after each test) recreate the rows with other ids. Thread-safe.
| Method | Result |
|---|---|
await get_id(model, *, for_concrete_model=True, session=None, content_type_model=...) | the content type id of a model class or instance: cached, or read with a Get operation (app_label, model) and cached |
await get_for_model(model, *, for_concrete_model=True, session=None, content_type_model=...) | the row as a new instance of the registered content type model, with the primary key, app_label and model loaded |
await get_model(content_type, *, session=None, content_type_model=...) | the registered model of a content type id |
await natural_keys(content_types, *, session=None, content_type_model=...) | {id: (app_label, model)} for the ids that have a row; one missing id is read with a Get, several with Select operations of up to 500 ids; None ids are skipped |
cached_id(model, *, for_concrete_model=True, session=None, content_type_model=...) | the cached id, None when it is not cached; runs nothing |
clear() | forgets every cached content type; a lookup running meanwhile does not store what it read |
No content type row raises the content type model's DoesNotExist when that model is registered, ObjectDoesNotExist otherwise, and nothing is cached. get_model() of a content type whose model is not registered raises LookupError, and so does get_for_model() when the content type model is not registered. A model class or instance that is not one raises TypeError.
from adorm import content_types
type_id = await content_types.get_id(Membership) # one Get, then cached
await content_types.get_id(membership) # an instance works too, no operation
content_types.cached_id(Membership) # the id, or None before the first lookup
await content_types.get_model(type_id) # Membership
row = await content_types.get_for_model(Membership) # ContentType(id=..., app_label="clubs", model="membership")
await content_types.get_id(Membership, session=reporting) # the id in the database of another profile
links = TaggedItem.objects.filter(content_type_id=await content_types.get_id(Location), object_id__in=ids)adorm.content_types
The process's ContentTypes instance, used by generic foreign keys and prefetches.
adorm.models.natural_key(model, *, for_concrete_model=True)
(app_label, model) of the content type of the model class or instance model: the parts of its label, the model name lowercased. With for_concrete_model a proxy gives its concrete model's key (ModelMeta.concrete_model). Raises TypeError for anything but a model class or instance.
natural_key(Membership) # ("clubs", "membership")
natural_key(PinnedNote) # ("club", "note")
natural_key(PinnedNote, for_concrete_model=False) # ("club", "pinnednote")adorm.models.get_generic_foreign_keys(model)
The GenericForeignKey descriptors of the model class model, inherited ones included, by attribute name.
get_generic_foreign_keys(InvoiceLine) # {"item": InvoiceLine.item}adorm.models.parent_link(model)
The ForeignKey stored in the primary key field of the model class model, the link of a multi-table inheritance child to its parent; None when the primary key is no relation's column. It names the parent model for create_from_parent().
parent_link(Competition).target # "activities.Activity"
parent_link(Activity) # Noneadorm.models.inheritance.own_fields(model, parent)
The fields of the model class model that the model class parent does not have, the primary key excepted: the fields a multi-table inheritance child declares itself.
own_fields(Competition, Activity) # ["discipline", "entry_deadline"]adorm.models.inheritance.child_values(model, values)
(parent_link(model), parent model class, validated values) for create_from_parent(): values validated with the field types of the child's own fields; a ForeignKey of the child given by name stands for its column (an instance for its primary key). Raises TypeError when model is not a multi-table inheritance child, ValueError for a name that is not one of the child's own fields or relations and for a value its type rejects (the message names the field).
child_values(Competition, {"discipline": "Sprint", "entry_deadline": "2026-05-01"})
# (Competition.activity_ptr, Activity, {"discipline": "Sprint", "entry_deadline": datetime.date(2026, 5, 1)})adorm.models.prefetch.normalize_lookups(current, lookups, prefix="")
current (a tuple of Prefetch objects) followed by lookups (relation paths or Prefetch objects) as Prefetch objects, with prefix put before each new path; what prefetch_related() keeps. A path that is already there is kept once; a new one with a query set or to_attr whose prefetch_to is already there raises ValueError, a lookup that is neither a string nor a Prefetch TypeError.
adorm.models.RelatedObject
The awaitable a ForeignKey, ReverseOneToOne or GenericForeignKey returns on an instance. Nothing runs until it is awaited; reading the relation without awaiting it creates no coroutine. Each await checks the cache.
adorm.models.get_relations(model)
The relation descriptors of the model class model, inherited ones included, by attribute name. A subclass removes an inherited relation by assigning the name to something else.
get_relations(Member) # {"club": Member.club, "sponsor": Member.sponsor}Managers
The managers topic explains which methods run in the client and which on the driver.
adorm.Manager(orm_name=None, *, method_manager=None)
A manager declared in a model class body. orm_name names the target ORM's manager the driver applies to every operation of this manager (Query.manager): its rows (Django: get_queryset()) and the overrides of its query set (create(), delete() …). None reads and writes the model's rows without manager logic, on every driver. method_manager names the target ORM's manager the driver methods run on and defaults to orm_name; a manager with a method_manager and no orm_name sends its queries without Query.manager, so they run on every driver, and only its driver methods need a driver that runs call operations. A name that is not a public identifier raises ValueError.
Reading the manager on a model class returns a copy bound to that class and the current session (a BoundModel); reading it on an instance or on an abstract model raises AttributeError. Subclasses of the model inherit its managers, bound to themselves. Declaring one manager instance under two names, and a manager named like a field or relation, raise TypeError.
A subclass adds methods: client-side ones that build on get_queryset(), driver methods, an overridden get_queryset(), and queryset_class, the QuerySet subclass of its query sets.
class OpenLoans(Manager):
queryset_class = LoanQuerySet
def get_queryset(self):
return super().get_queryset().filter(archived=False)
class Loan(Model):
_meta = ModelMeta("library.Loan")
id: int | None = None
archived: bool = False
objects = OpenLoans("objects")
all_loans = Manager()
class User(Model):
...
objects = UserManager(method_manager="objects") # create_user() on the driver, queries on every driverManager.from_queryset(queryset_class, class_name=None)
Class method: a subclass of the manager class with queryset_class set; its name is class_name, or <Manager class name>From<QuerySet class name>. A class that is not a QuerySet subclass raises TypeError.
LoanManager = Manager.from_queryset(LoanQuerySet)
objects = LoanManager("objects")adorm.driver_method(func, *, queryset_only=False)
Declares an async def method of a Manager or QuerySet subclass as a method the driver runs, returning a DriverMethod. Used bare (@driver_method) or with arguments (@driver_method(queryset_only=True)). The declaration's signature is the method's: a call checks its arguments against it (TypeError before anything is sent), and the annotations type the arguments' encoding. The body does not run. queryset_only keeps a query set method off the manager (Django's queryset_only).
A function that is not a coroutine function or has no self parameter raises TypeError; a name starting with _ raises ValueError; so does assigning it to a class attribute of another name.
class LoanQuerySet(QuerySet):
@driver_method
async def archive(self, reason: str = "") -> int:
"""Archive the loans; returns their number."""
class LoanManager(Manager):
queryset_class = LoanQuerySet
@driver_method
async def lend(self, reader_id: int, book_id: str, *, days: int = 14) -> "Loan": ...
await Loan.objects.lend(7, "9780000000001")
await Loan.objects.filter(reader_id=7).archive("moved")adorm.models.DriverMethod
What driver_method returns: a descriptor that, read on an instance, gives a bound method returning a coroutine.
| Member | Meaning |
|---|---|
func | the declared function |
name | the method name |
signature | the declared inspect.Signature |
queryset_only | whether the manager leaves it to its query sets |
schema | the MethodSchema of the parameters after self; a string annotation is evaluated in the function's module, and one that does not evaluate types nothing |
Calling it on a bound manager sends Call(Query(label, manager=orm_name), name, "manager", args, kwargs, method_manager); on a query set, Call(qs.query, name, "queryset", args, kwargs, manager), where manager is the query's Query.manager or else the method_manager of the model's first manager whose queryset_class declares the method (Call). No such manager raises TypeError, and so does an instance of any other class. The result is the driver's, with every ModelRow, also inside lists, tuples and the values of mappings, turned into an instance of the registered model on the same session; a row of a model that is not registered raises InterfaceError. A DoesNotExist or MultipleObjectsReturned the driver raises becomes the model's.
LoanManager.lend.schema.kwarg_type("days") # intadorm.models.get_managers(model)
The manager declarations of model (inherited ones included) by attribute name, unbound.
list(get_managers(Loan)) # ["objects", "all_loans"]adorm.models.driver_methods(model)
The DriverMethod of every manager of model that has a method_manager, by (method_manager, target, method): the manager's own methods with the target "manager", the methods of its queryset_class with "queryset".
dict(driver_methods(Loan))
# {("objects", "manager", "lend"): LoanManager.lend, ("objects", "queryset", "archive"): LoanQuerySet.archive}adorm.models.find_driver_method(label, manager, target, method)
The driver method method declared for target of the ORM manager manager on the registered model label. DriverConnection.execute() looks up every Call with it; a driver runs only declared methods. A model that is not registered, a manager of None and a method the model does not declare raise NotSupportedError.
find_driver_method("library.Loan", "objects", "queryset", "archive") # LoanQuerySet.archive
find_driver_method("library.Loan", "objects", "queryset", "delete") # NotSupportedErrorExecutors
adorm.models.Executor
The protocol of what runs operations for model instances: await executor.execute(operation) returns the operation's result (a row for Get, the stored values for Save). An instance uses its own executor (_state.executor); without one it asks the executor resolver.
class Recorder:
def __init__(self):
self.operations = []
async def execute(self, operation):
self.operations.append(operation)
return {"id": 1}adorm.models.set_executor_resolver(resolver)
Set the function that gives an instance without its own executor one: resolver(model_class) returns an Executor or None. Returns the previous resolver; None removes it. Importing adorm installs a resolver that returns the current session. Without an executor, save() and relation loads raise InterfaceError.
previous = set_executor_resolver(lambda model: executor)
await Member(name="Ana").save() # runs on executor
set_executor_resolver(previous)Registry
adorm.models.ModelRegistry
Model classes by label, and a SchemaSource serving each registered model's schema.
| Member | Meaning |
|---|---|
register(model) | register under model._meta.label; a class with the same module and qualified name replaces the registered one, another class raises ValueError |
unregister(label) | remove the model; an unknown label is ignored |
get(label) | the model class; LookupError when none is registered |
get_for_content_type(app_label, model_name) | the model class whose label has the app part app_label and the model part model_name, compared case-insensitively (Django's ContentType.model); LookupError when none is registered |
schema_hashes() | the schema hash of every registered model that has one (_meta.schema_hash), as a dict by label; the schema_hashes argument of Driver.check() |
model_schema(label) | the model's ModelSchema, None for an unknown label; cached once the model class is complete (its forward references resolved) |
label in registry, iter(registry), len(registry) | membership, the model classes, their number |
adorm.models.registry
The ModelRegistry every model with _meta registers in. It types operation values for encoding:
operation = Save("club.Member", 3, {"fee": decimal.Decimal("1.50")})
data = operation.to_dict(registry) # {"fee": {"value": "1.50"}, ...}
assert Operation.from_dict(data, registry) == operation
registry.schema_hashes() # {"clubs.Club": "e8c2eed312ab7b68", ...}adorm.models.model_schema(model)
The ModelSchema of the model class model: its label, primary key, the type of every field (with its pydantic constraints), the target label of every relation, _meta.orm_names and the MethodSchema of every driver method. An abstract model raises TypeError.
schema = model_schema(Member)
schema.fields["club_id"] # int | None
schema.relations # {"club": "club.Club"}