loom.core.model

class loom.core.model.BaseModel

Bases: Struct

Base for all loom domain models.

Subclasses must declare __tablename__ and provide typed attributes. Column metadata is optional via ColumnField(...).

class loom.core.model.TimestampedModel(*, created_at=UNSET, updated_at=UNSET)

Bases: BaseModel

Opt-in base for domain models that need audit timestamps.

Adds created_at and updated_at as nullable server-default columns. Both fields are omitted from serialisation output when None (omit_defaults=True is inherited from BaseModel).

Design note: trace_id is intentionally absent. Trace identifiers are an observability concern belonging to the transport layer, not to the domain model. Correlating a record with the request that created it is the responsibility of structured logs and SQL query comments — not of a model field.

Parameters:

• created_at (datetime | None)

• updated_at (datetime | None)

created_at

UTC timestamp set by the database at INSERT time. None until the first flush/commit.

Type:

datetime.datetime | None

updated_at

UTC timestamp updated by the database on every UPDATE. None until the first flush/commit.

Type:

datetime.datetime | None

Example:

class Product(TimestampedModel):
    __tablename__ = "products"
    id:   int = ColumnField(primary_key=True, autoincrement=True)
    name: str

class loom.core.model.Cardinality(value)

Bases: StrEnum

class loom.core.model.ColumnFieldInfo(name, python_type, column_type, field)

Bases: object

Resolved metadata for a single column field.

Parameters:

• name (str)

• python_type (type)

• column_type (ColumnType)

• field (Field)

loom.core.model.ColumnField(column_type=None, *, primary_key=False, unique=False, index=False, nullable=False, autoincrement=False, server_default=None, server_onupdate=None, foreign_key=None, on_delete=None, default=msgspec.UNSET, length=None, db_type=None)

Declare column metadata without using explicit Annotated syntax.

Parameters:

• column_type (ColumnType | None)

• primary_key (bool)

• unique (bool)

• index (bool)

• nullable (bool)

• autoincrement (bool)

• server_default (ServerDefault | None)

• server_onupdate (ServerOnUpdate | str | None)

• foreign_key (str | None)

• on_delete (OnDelete | None)

• default (Any)

• length (int | None)

• db_type (ColumnType | None)

Return type:

Any

class loom.core.model.ColumnType(type_name, args=(), kwargs=<factory>)

Bases: object

Backend column type descriptor stored inside Annotated[...].

Parameters:

• type_name (str)

• args (tuple[Any, ...])

• kwargs (dict[str, Any])

class loom.core.model.Field(primary_key=False, unique=False, index=False, nullable=False, autoincrement=False, server_default=None, server_onupdate=None, foreign_key=None, on_delete=None, default=UNSET, length=None)

Bases: object

Column constraint metadata stored inside Annotated[...].

Parameters:

• primary_key (bool)

• unique (bool)

• index (bool)

• nullable (bool)

• autoincrement (bool)

• server_default (ServerDefault | None)

• server_onupdate (ServerOnUpdate | str | None)

• foreign_key (str | None)

• on_delete (OnDelete | None)

• default (Any)

• length (int | None)

loom.core.model.ProjectionField(*, loader, profiles=('default',), depends_on=(), default=PROJECTION_DEFAULT_MISSING)

Declare a projection field without triggering assignment type errors.

Parameters:

• loader (Any) – Loader descriptor or instance responsible for computing the value.

• profiles (tuple[str, ...]) – Profile names in which this projection is active.

• depends_on (tuple[str, ...]) – Names of other projections or relation events this depends on.

• default (Any) – Fallback value when the loader returns no result for an entity.

Returns:

A Projection instance cast to Any for clean class-body assignment.

Return type:

Any

Example:

count_reviews: int = ProjectionField(
    loader=CountLoader(model=ProductReview),
    profiles=("with_details",),
    default=0,
)

class loom.core.model.LoomStructMeta(name, bases, namespace, **kwargs)

Bases: StructMeta

Metaclass that intercepts Relation and Projection assignments before StructMeta processes the class body.

Each intercepted attribute is replaced with UNSET as its default, and the type annotation is widened to T | UnsetType so that omit_defaults=True strips unloaded fields from serialisation output.

class loom.core.model.OnDelete(value)

Bases: StrEnum

class loom.core.model.OnUpdate(value)

Bases: StrEnum

class loom.core.model.Projection(loader, profiles=('default', ), depends_on=(), default=<object object>)

Bases: object

Derived-field metadata assigned as a class attribute on a BaseModel.

Parameters:

• loader (Any)

• profiles (tuple[str, ...])

• depends_on (tuple[str, ...])

• default (Any)

class loom.core.model.Relation(foreign_key, cardinality, secondary=None, back_populates=None, on_delete=None, on_update=None, profiles=('default',), depends_on=(), default=None)

Bases: object

Relationship metadata assigned as a class attribute on a BaseModel.

Parameters:

• foreign_key (str)

• cardinality (Cardinality)

• secondary (str | None)

• back_populates (str | None)

• on_delete (OnDelete | None)

• on_update (OnUpdate | None)

• profiles (tuple[str, ...])

• depends_on (tuple[str, ...])

• default (Any)

loom.core.model.RelationField(*, foreign_key, cardinality, secondary=None, back_populates=None, on_delete=None, on_update=None, profiles=('default',), depends_on=(), default=None)

Declare a relation field with normal typing (without assignment type errors).

Parameters:

• foreign_key (str)

• cardinality (Cardinality)

• secondary (str | None)

• back_populates (str | None)

• on_delete (OnDelete | None)

• on_update (OnUpdate | None)

• profiles (tuple[str, ...])

• depends_on (tuple[str, ...])

• default (Any)

Return type:

Any

class loom.core.model.ServerDefault(value)

Bases: StrEnum

class loom.core.model.ServerOnUpdate(value)

Bases: StrEnum

loom.core.model.get_column_fields(cls)

Extract column fields from a model class.

Parameters:

cls (type)

Return type:

dict[str, ColumnFieldInfo]

loom.core.model.get_id_attribute(cls)

Return the name of the primary key field.

Parameters:

cls (type)

Return type:

str

loom.core.model.get_projections(cls)

Return projections registered by LoomStructMeta.

Parameters:

cls (type)

Return type:

dict[str, Projection]

loom.core.model.get_relations(cls)

Return relations registered by LoomStructMeta.

Parameters:

cls (type)

Return type:

dict[str, Relation]

loom.core.model.get_table_name(cls)

Return the __tablename__ declared on the model.

Parameters:

cls (type)

Return type:

str