ormar/docs/api/models/model.md

models.model

group_related_list

group_related_list(list_: List) -> Dict

Translates the list of related strings into a dictionary. That way nested models are grouped to traverse them in a right order and to avoid repetition.

Sample: ["people__houses", "people__cars__models", "people__cars__colors"] will become: {'people': {'houses': [], 'cars': ['models', 'colors']}}

Arguments:

• list_ (List[str]): list of related models used in select related

Returns:

(Dict[str, List]): list converted to dictionary to avoid repetition and group nested models

Model Objects

class Model(NewBaseModel)

from_row

 | @classmethod
 | from_row(cls: Type[T], row: sqlalchemy.engine.ResultProxy, select_related: List = None, related_models: Any = None, previous_model: Type[T] = None, related_name: str = None, fields: Optional[Union[Dict, Set]] = None, exclude_fields: Optional[Union[Dict, Set]] = None) -> Optional[T]

Model method to convert raw sql row from database into ormar.Model instance. Traverses nested models if they were specified in select_related for query.

Called recurrently and returns model instance if it's present in the row. Note that it's processing one row at a time, so if there are duplicates of parent row that needs to be joined/combined (like parent row in sql join with 2+ child rows) instances populated in this method are later combined in the QuerySet. Other method working directly on raw database results is in prefetch_query, where rows are populated in a different way as they do not have nested models in result.

Arguments:

• row (sqlalchemy.engine.result.ResultProxy): raw result row from the database
• select_related (List): list of names of related models fetched from database
• related_models (Union[List, Dict]): list or dict of related models
• previous_model (Model class): internal param for nested models to specify table_prefix
• related_name (str): internal parameter - name of current nested model
• fields (Optional[Union[Dict, Set]]): fields and related model fields to include if provided only those are included
• exclude_fields (Optional[Union[Dict, Set]]): fields and related model fields to exclude excludes the fields even if they are provided in fields

Returns:

(Optional[Model]): returns model if model is populated from database

populate_nested_models_from_row

 | @classmethod
 | populate_nested_models_from_row(cls, item: dict, row: sqlalchemy.engine.ResultProxy, related_models: Any, fields: Optional[Union[Dict, Set]] = None, exclude_fields: Optional[Union[Dict, Set]] = None) -> dict

Traverses structure of related models and populates the nested models from the database row. Related models can be a list if only directly related models are to be populated, converted to dict if related models also have their own related models to be populated.

Recurrently calls from_row method on nested instances and create nested instances. In the end those instances are added to the final model dictionary.

Arguments:

• item (Dict): dictionary of already populated nested models, otherwise empty dict
• row (sqlalchemy.engine.result.ResultProxy): raw result row from the database
• related_models (Union[Dict, List]): list or dict of related models
• fields (Optional[Union[Dict, Set]]): fields and related model fields to include - if provided only those are included
• exclude_fields (Optional[Union[Dict, Set]]): fields and related model fields to exclude excludes the fields even if they are provided in fields

Returns:

(Dict): dictionary with keys corresponding to model fields names and values are database values

extract_prefixed_table_columns

 | @classmethod
 | extract_prefixed_table_columns(cls, item: dict, row: sqlalchemy.engine.result.ResultProxy, table_prefix: str, fields: Optional[Union[Dict, Set]] = None, exclude_fields: Optional[Union[Dict, Set]] = None) -> dict

Extracts own fields from raw sql result, using a given prefix. Prefix changes depending on the table's position in a join.

If the table is a main table, there is no prefix. All joined tables have prefixes to allow duplicate column names, as well as duplicated joins to the same table from multiple different tables.

Extracted fields populates the item dict later used to construct a Model.

Used in Model.from_row and PrefetchQuery._populate_rows methods.

Arguments:

• item (Dict): dictionary of already populated nested models, otherwise empty dict
• row (sqlalchemy.engine.result.ResultProxy): raw result row from the database
• table_prefix (str): prefix of the table from AliasManager each pair of tables have own prefix (two of them depending on direction) - used in joins to allow multiple joins to the same table.
• fields (Optional[Union[Dict, Set]]): fields and related model fields to include - if provided only those are included
• exclude_fields (Optional[Union[Dict, Set]]): fields and related model fields to exclude excludes the fields even if they are provided in fields

Returns:

(Dict): dictionary with keys corresponding to model fields names and values are database values

upsert

 | async upsert(**kwargs: Any) -> T

Performs either a save or an update depending on the presence of the pk. If the pk field is filled it's an update, otherwise the save is performed. For save kwargs are ignored, used only in update if provided.

Arguments:

• kwargs (Any): list of fields to update

Returns:

(Model): saved Model

save

 | async save() -> T

Performs a save of given Model instance. If primary key is already saved, db backend will throw integrity error.

Related models are saved by pk number, reverse relation and many to many fields are not saved - use corresponding relations methods.

If there are fields with server_default set and those fields are not already filled save will trigger also a second query to refreshed the fields populated server side.

Does not recognize if model was previously saved. If you want to perform update or insert depending on the pk fields presence use upsert.

Sends pre_save and post_save signals.

Sets model save status to True.

Returns:

(Model): saved Model

save_related

 | async save_related(follow: bool = False, visited: Set = None, update_count: int = 0) -> int

Triggers a upsert method on all related models if the instances are not already saved. By default saves only the directly related ones.

If follow=True is set it saves also related models of related models.

To not get stuck in an infinite loop as related models also keep a relation to parent model visited models set is kept.

That way already visited models that are nested are saved, but the save do not follow them inside. So Model A -> Model B -> Model A -> Model C will save second Model A but will never follow into Model C. Nested relations of those kind need to be persisted manually.

Arguments:

• follow (bool): flag to trigger deep save - by default only directly related models are saved with follow=True also related models of related models are saved
• visited (Set): internal parameter for recursive calls - already visited models
• update_count (int): internal parameter for recursive calls - number of updated instances

Returns:

(int): number of updated/saved models

_update_and_follow

 | @staticmethod
 | async _update_and_follow(rel: T, follow: bool, visited: Set, update_count: int) -> Tuple[int, Set]

Internal method used in save_related to follow related models and update numbers of updated related instances.

Arguments:

• rel (Model): Model to follow
• follow (bool): flag to trigger deep save - by default only directly related models are saved with follow=True also related models of related models are saved
• visited (Set): internal parameter for recursive calls - already visited models
• update_count (int): internal parameter for recursive calls - number of updated instances

Returns:

(Tuple[int, Set]): tuple of update count and visited

update

 | async update(**kwargs: Any) -> T

Performs update of Model instance in the database. Fields can be updated before or you can pass them as kwargs.

Sends pre_update and post_update signals.

Sets model save status to True.

Raises:

• ModelPersistenceError: If the pk column is not set

Arguments:

• kwargs (Any): list of fields to update as field=value pairs

Returns:

(Model): updated Model

delete

 | async delete() -> int

Removes the Model instance from the database.

Sends pre_delete and post_delete signals.

Sets model save status to False.

Note it does not delete the Model itself (python object). So you can delete and later save (since pk is deleted no conflict will arise) or update and the Model will be saved in database again.

Returns:

(int): number of deleted rows (for some backends)

load

 | async load() -> T

Allow to refresh existing Models fields from database. Be careful as the related models can be overwritten by pk_only models in load. Does NOT refresh the related models fields if they were loaded before.

Raises:

• NoMatch: If given pk is not found in database.

Returns:

(Model): reloaded Model