orionis.orm.Model

THE ORIONIS API

Build with clarity.

Explore the building blocks of an async-first Python framework. Every module, class, and method — connected, searchable, and ready to build with.

Explore modules View classes

class documentation

class Model(AttributesMixin, StateMixin, RelationsMixin, EventsMixin, SoftDeletesMixin): (source)

Constructors: Model._newFromDatabase(row), Model.create(attributes), Model.findOrFail(key), Model.firstOrFail(), Model(attributes)

View In Hierarchy

Base class of the Orionis active-record models.

Concrete models declare their columns with the fluent schema types and interact with the database exclusively through the Orionis query builder; the underlying SQL engine never surfaces. Class-level entry points such as where or orderBy start a builder implicitly.

Class Method	`_newFromDatabase`	Hydrate a model instance from a database row.
Class Method	`addGlobalScope`	Register a constraint applied to every query of this model.
Async Class Method	`all`	Retrieve every row of the model table.
Async Class Method	`create`	Create, persist, and return a new model.
Async Class Method	`destroy`	Delete the models matching the given primary keys.
Async Class Method	`find`	Retrieve a model by its primary key.
Async Class Method	`findOrFail`	Retrieve a model by primary key or raise when absent.
Async Class Method	`first`	Retrieve the first row of the model table.
Async Class Method	`firstOrFail`	Retrieve the first row or raise when the table is empty.
Class Method	`freshTimestamp`	Produce the current timestamp for persistence operations.
Class Method	`getConnection`	Resolve the connection configured for this model.
Class Method	`newUniqueId`	Produce a client-generated primary key value.
Class Method	`query`	Start a new query builder bound to this model.
Class Method	`removeGlobalScope`	Unregister a previously added global scope.
Method	`__getattr__`	Serve column values and accessor-backed attributes.
Method	`__init__`	Initialize a new, unsaved model instance.
Method	`__repr__`	Return a concise developer representation of the model.
Method	`__setattr__`	Route column assignments into the attribute store.
Async Method	`_performForceDelete`	Remove the persisted row permanently.
Async Method	`_performInsert`	Insert the model attributes as a new row.
Async Method	`_performUpdate`	Write the dirty attributes of an existing model.
Method	`_primaryKeyValue`	Return the primary key value identifying the stored row.
Async Method	`delete`	Delete the model row, honoring soft deletes when enabled.
Async Method	`save`	Persist the model, inserting or updating as appropriate.
Async Method	`update`	Mass assign the given attributes and persist the model.
Constant	`CREATED_AT`	Undocumented
Constant	`DELETED_AT`	Undocumented
Constant	`UPDATED_AT`	Undocumented
Class Variable	`__abstract__`	Undocumented
Class Variable	`__meta__`	Undocumented
Class Variable	`__slots__`	Undocumented
Class Variable	`appends`	Undocumented
Class Variable	`casts`	Undocumented
Class Variable	`connection`	Undocumented
Class Variable	`fillable`	Undocumented
Class Variable	`guarded`	Undocumented
Class Variable	`hidden`	Undocumented
Class Variable	`incrementing`	Undocumented
Class Variable	`primary_key`	Undocumented
Class Variable	`soft_deletes`	Undocumented
Class Variable	`table`	Undocumented
Class Variable	`table_definition`	Undocumented
Class Variable	`timestamps`	Undocumented
Class Variable	`uuids`	Undocumented
Instance Variable	`_changes`	Undocumented
Instance Variable	`_exists`	Undocumented

Inherited from AttributesMixin:

Method	`exclude`	Return every attribute except the given keys.
Method	`fill`	Mass assign the given attributes honoring the assignment rules.
Method	`getAttribute`	Return a single attribute value through its accessor.
Method	`hasAccessor`	Report whether an attribute is served by an accessor.
Method	`only`	Return a subset of attributes limited to the given keys.
Method	`serialize`	Serialize the model for collection-level serialization.
Method	`setAttribute`	Assign a single attribute applying its mutator and cast.
Method	`toDict`	Serialize the visible attributes into a dictionary.
Method	`toJson`	Serialize the visible attributes into a JSON string.

Inherited from StateMixin (via AttributesMixin):

Method	`getChanges`	Return the attributes persisted by the last save operation.
Method	`getDirty`	Return the attributes modified since the last sync.
Method	`getOriginal`	Return the original attribute snapshot or a single original value.
Method	`isClean`	Report whether no attribute changed since the last sync.
Method	`isDirty`	Report whether any attribute changed since the last sync.
Method	`syncOriginal`	Snapshot the current attributes as the new original state.
Method	`wasChanged`	Report whether the last save operation changed any attribute.

Inherited from RelationsMixin (via AttributesMixin, StateMixin):

Method	`belongsTo`	Define the inverse of a `hasOne`/`hasMany` relationship.
Method	`belongsToMany`	Define a many-to-many relationship backed by a pivot table.
Method	`getRelation`	Return an already-resolved relationship result.
Method	`hasMany`	Define a one-to-many relationship owned by the related table.
Method	`hasOne`	Define a one-to-one relationship owned by the related table.
Method	`relationLoaded`	Report whether a relationship result has already been resolved.
Method	`setRelation`	Store an already-resolved relationship result.

Inherited from EventsMixin (via AttributesMixin, StateMixin, RelationsMixin):

Class Method	`flushEvents`	Remove registered listeners from the model.
Class Method	`observe`	Register every lifecycle method exposed by an observer.
Class Method	`registerEvent`	Register a listener for a model lifecycle event.
Async Method	`fireEvent`	Dispatch a lifecycle event to its listeners.

Inherited from SoftDeletesMixin (via AttributesMixin, StateMixin, RelationsMixin, EventsMixin):

Async Method	`_performSoftDelete`	Stamp the soft delete column of the persisted row.
Async Method	`forceDelete`	Delete the row permanently, ignoring soft deletes.
Async Method	`restore`	Bring a soft deleted row back by clearing its delete stamp.
Method	`trashed`	Report whether the instance is currently soft deleted.

@classmethod

def _newFromDatabase(cls, row: dict[str, Any]) -> Model: (source) ¶

Hydrate a model instance from a database row.

Parameters
row:`dict`	Raw row values keyed by column name. The mapping is not shared with any other caller, so it is adopted and mutated in place instead of being copied.

Returns
`Model`	Existing model instance with casts applied.

@classmethod

def addGlobalScope(cls, name: str, scope: Callable[[ModelQueryBuilder[Any]], None]) -> type[Model]: (source) ¶

Parameters
name:`str`	Name the scope is registered under, used to disable it later with `withoutGlobalScope`.
scope:`Callable`	Callable receiving the builder and constraining it in place.

Returns
`type`	The model class, enabling fluent chaining.

@classmethod

async def all(cls) -> Collection: (source) ¶

Retrieve every row of the model table.

Returns
`Collection`	Collection of hydrated model instances.

@classmethod

async def create(cls, attributes: dict[str, Any]) -> Model: (source) ¶

Create, persist, and return a new model.

Parameters
attributes:`dict`	Attributes to mass assign honoring the fillable rules.

Returns
`Model`	Persisted model instance.

Raises
`MassAssignmentException`	If an attribute violates the mass assignment rules.
`QueryException`	If the insert statement fails.

@classmethod

async def destroy(cls, *keys: Any) -> int: (source) ¶

Delete the models matching the given primary keys.

Parameters
*keys:`Any`	Primary key values to delete.

Returns
`int`	Number of deleted rows.

@classmethod

async def find(cls, key: Any) -> Model | None: (source) ¶

Retrieve a model by its primary key.

Parameters
key:`Any`	Primary key value to look up.

Returns
`Model or None`	Matching model, or `None` when absent.

@classmethod

async def findOrFail(cls, key: Any) -> Model: (source) ¶

Retrieve a model by primary key or raise when absent.

Parameters
key:`Any`	Primary key value to look up.

Returns
`Model`	Matching model.

Raises
`ModelNotFoundException`	If no record matches the key.

@classmethod

async def first(cls) -> Model | None: (source) ¶

Retrieve the first row of the model table.

Returns
`Model or None`	First model, or `None` when the table is empty.

@classmethod

async def firstOrFail(cls) -> Model: (source) ¶

Retrieve the first row or raise when the table is empty.

Returns
`Model`	First model.

Raises
`ModelNotFoundException`	If the table has no rows.

@classmethod

def freshTimestamp(cls) -> datetime: (source) ¶

Produce the current timestamp for persistence operations.

Timezone-aware timestamps are produced when the update column is a timezone-aware type, naive UTC otherwise.

Returns
`datetime`	Current UTC timestamp.

@classmethod

def getConnection(cls) -> IConnection: (source) ¶

Resolve the connection configured for this model.

Returns
`IConnection`	Connection used for model queries and persistence.

Raises
`OrmConfigurationException`	If no connection manager has been installed.
`ConnectionNotFoundException`	If the configured connection is not declared.

@classmethod

def newUniqueId(cls) -> Any: (source) ¶

Produce a client-generated primary key value.

Overridable by models needing a different identifier scheme, such as ULIDs or prefixed keys.

Returns
`Any`	Fresh unique identifier.

@classmethod

def query(cls) -> ModelQueryBuilder[Any]: (source) ¶

Start a new query builder bound to this model.

Returns
`ModelQueryBuilder`	Fresh builder targeting the model table.

@classmethod

def removeGlobalScope(cls, name: str) -> type[Model]: (source) ¶

Unregister a previously added global scope.

Parameters
name:`str`	Name the scope was registered under.

Returns
`type`	The model class, enabling fluent chaining.

def __getattr__(self, key: str) -> Any: (source) ¶

Serve column values and accessor-backed attributes.

Parameters
key:`str`	Attribute name being accessed.

Returns
`Any`	Attribute value; `None` for declared but unloaded columns.

Raises
`AttributeError`	If the name is neither loaded, a declared column, nor an accessor-backed attribute.

def __init__(self, attributes: dict[str, Any] | None = None): (source) ¶

Initialize a new, unsaved model instance.

Parameters
attributes:`dict or None, optional`	Attributes to mass assign honoring the fillable rules.

Returns
`None`	This method does not return a value.

Raises
`MassAssignmentException`	If an attribute violates the mass assignment rules.

def __repr__(self) -> str: (source) ¶

Return a concise developer representation of the model.

Returns
`str`	Representation including the class name and primary key.

def __setattr__(self, key: str, value: Any): (source) ¶

Route column assignments into the attribute store.

Parameters
key:`str`	Attribute name being assigned.
value:`Any`	Value to assign.

Returns
`None`	This method does not return a value.

async def _performForceDelete(self) -> bool: (source) ¶

Remove the persisted row permanently.

Returns
`bool`	`True` when a row was removed.

Raises
`QueryException`	If the statement fails to execute.

async def _performInsert(self) -> bool: (source) ¶

Insert the model attributes as a new row.

Returns
`bool`	`True` when the insert succeeds.

Raises
`QueryException`	If the statement fails to execute.

async def _performUpdate(self) -> bool: (source) ¶

Write the dirty attributes of an existing model.

Returns
`bool`	`True` when a row was written or nothing changed, `False` when no stored row matched the primary key.

Raises
`QueryException`	If the statement fails to execute.

def _primaryKeyValue(self) -> Any: (source) ¶

Return the primary key value identifying the stored row.

The original value is preferred so a dirty primary key still targets the persisted row.

Returns
`Any`	Primary key value.

async def delete(self) -> bool: (source) ¶

Delete the model row, honoring soft deletes when enabled.

Models declaring soft_deletes stamp their delete column instead of removing the row; every other model is deleted permanently.

Returns
`bool`	`True` when a row was deleted or stamped, `False` for unsaved models or when a listener vetoed the operation.

Raises
`QueryException`	If the statement fails to execute.

async def save(self) -> bool: (source) ¶

Persist the model, inserting or updating as appropriate.

New models are inserted, receiving their generated primary key; existing models write only their dirty attributes. Timestamps are maintained automatically when enabled, and the saving, creating/updating, created/updated and saved events are dispatched around the write.