next part of the docs and api documentation in beta ver

2021-01-04 19:38:21 +01:00
parent eec17e2f78
commit 9f8e8e87e8
64 changed files with 7414 additions and 37 deletions
--- a/docs/api/models/helpers/models.md
+++ b/docs/api/models/helpers/models.md
@ -0,0 +1,64 @@
+<a name="models.helpers.models"></a>
+# models.helpers.models
+
+<a name="models.helpers.models.populate_default_options_values"></a>
+#### populate\_default\_options\_values
+
+```python
+populate_default_options_values(new_model: Type["Model"], model_fields: Dict) -> None
+```
+
+Sets all optional Meta values to it's defaults
+and set model_fields that were already previously extracted.
+
+Here should live all options that are not overwritten/set for all models.
+
+Current options are:
+* constraints = []
+* abstract = False
+
+**Arguments**:
+
+- `new_model (Model class)`: newly constructed Model
+- `model_fields (Union[Dict[str, type], Dict])`: 
+
+<a name="models.helpers.models.extract_annotations_and_default_vals"></a>
+#### extract\_annotations\_and\_default\_vals
+
+```python
+extract_annotations_and_default_vals(attrs: Dict) -> Tuple[Dict, Dict]
+```
+
+Extracts annotations from class namespace dict and triggers
+extraction of ormar model_fields.
+
+**Arguments**:
+
+- `attrs (Dict)`: namespace of the class created
+
+**Returns**:
+
+`(Tuple[Dict, Dict])`: namespace of the class updated, dict of extracted model_fields
+
+<a name="models.helpers.models.validate_related_names_in_relations"></a>
+#### validate\_related\_names\_in\_relations
+
+```python
+validate_related_names_in_relations(model_fields: Dict, new_model: Type["Model"]) -> None
+```
+
+Performs a validation of relation_names in relation fields.
+If multiple fields are leading to the same related model
+only one can have empty related_name param
+(populated by default as model.name.lower()+'s').
+Also related_names have to be unique for given related model.
+
+**Raises**:
+
+- `ModelDefinitionError`: if validation of related_names fail
+
+**Arguments**:
+
+- `model_fields (Dict[str, ormar.Field])`: dictionary of declared ormar model fields
+- `new_model (Model class)`: 
+
--- a/docs/api/models/helpers/pydantic.md
+++ b/docs/api/models/helpers/pydantic.md
@ -0,0 +1,122 @@
+<a name="models.helpers.pydantic"></a>
+# models.helpers.pydantic
+
+<a name="models.helpers.pydantic.create_pydantic_field"></a>
+#### create\_pydantic\_field
+
+```python
+create_pydantic_field(field_name: str, model: Type["Model"], model_field: Type[ManyToManyField]) -> None
+```
+
+Registers pydantic field on through model that leads to passed model
+and is registered as field_name passed.
+
+Through model is fetched from through attributed on passed model_field.
+
+**Arguments**:
+
+- `field_name (str)`: field name to register
+- `model (Model class)`: type of field to register
+- `model_field (ManyToManyField class)`: relation field from which through model is extracted
+
+<a name="models.helpers.pydantic.get_pydantic_field"></a>
+#### get\_pydantic\_field
+
+```python
+get_pydantic_field(field_name: str, model: Type["Model"]) -> "ModelField"
+```
+
+Extracts field type and if it's required from Model model_fields by passed
+field_name. Returns a pydantic field with type of field_name field type.
+
+**Arguments**:
+
+- `field_name (str)`: field name to fetch from Model and name of pydantic field
+- `model (Model class)`: type of field to register
+
+**Returns**:
+
+`(pydantic.ModelField)`: newly created pydantic field
+
+<a name="models.helpers.pydantic.populate_default_pydantic_field_value"></a>
+#### populate\_default\_pydantic\_field\_value
+
+```python
+populate_default_pydantic_field_value(ormar_field: Type[BaseField], field_name: str, attrs: dict) -> dict
+```
+
+Grabs current value of the ormar Field in class namespace
+(so the default_value declared on ormar model if set)
+and converts it to pydantic.FieldInfo
+that pydantic is able to extract later.
+
+On FieldInfo there are saved all needed params like max_length of the string
+and other constraints that pydantic can use to build
+it's own field validation used by ormar.
+
+**Arguments**:
+
+- `ormar_field (ormar Field)`: field to convert
+- `field_name (str)`: field to convert name
+- `attrs (Dict)`: current class namespace
+
+**Returns**:
+
+`(Dict)`: updated namespace dict
+
+<a name="models.helpers.pydantic.populate_pydantic_default_values"></a>
+#### populate\_pydantic\_default\_values
+
+```python
+populate_pydantic_default_values(attrs: Dict) -> Tuple[Dict, Dict]
+```
+
+Extracts ormar fields from annotations (deprecated) and from namespace
+dictionary of the class. Fields declared on model are all subclasses of the
+BaseField class.
+
+Trigger conversion of ormar field into pydantic FieldInfo, which has all needed
+paramaters saved.
+
+Overwrites the annotations of ormar fields to corresponding types declared on
+ormar fields (constructed dynamically for relations).
+Those annotations are later used by pydantic to construct it's own fields.
+
+**Arguments**:
+
+- `attrs (Dict)`: current class namespace
+
+**Returns**:
+
+`(Tuple[Dict, Dict])`: namespace of the class updated, dict of extracted model_fields
+
+<a name="models.helpers.pydantic.get_pydantic_base_orm_config"></a>
+#### get\_pydantic\_base\_orm\_config
+
+```python
+get_pydantic_base_orm_config() -> Type[BaseConfig]
+```
+
+Returns empty pydantic Config with orm_mode set to True.
+
+**Returns**:
+
+`(pydantic Config)`: empty default config with orm_mode set.
+
+<a name="models.helpers.pydantic.get_potential_fields"></a>
+#### get\_potential\_fields
+
+```python
+get_potential_fields(attrs: Dict) -> Dict
+```
+
+Gets all the fields in current class namespace that are Fields.
+
+**Arguments**:
+
+- `attrs (Dict)`: current class namespace
+
+**Returns**:
+
+`(Dict)`: extracted fields that are ormar Fields
+
--- a/docs/api/models/helpers/relations.md
+++ b/docs/api/models/helpers/relations.md
@ -0,0 +1,154 @@
+<a name="models.helpers.relations"></a>
+# models.helpers.relations
+
+<a name="models.helpers.relations.alias_manager"></a>
+#### alias\_manager
+
+<a name="models.helpers.relations.register_relation_on_build"></a>
+#### register\_relation\_on\_build
+
+```python
+register_relation_on_build(new_model: Type["Model"], field_name: str) -> None
+```
+
+Registers ForeignKey relation in alias_manager to set a table_prefix.
+Registration include also reverse relation side to be able to join both sides.
+
+Relation is registered by model name and relation field name to allow for multiple
+relations between two Models that needs to have different
+aliases for proper sql joins.
+
+**Arguments**:
+
+- `new_model (Model class)`: constructed model
+- `field_name (str)`: name of the related field
+
+<a name="models.helpers.relations.register_many_to_many_relation_on_build"></a>
+#### register\_many\_to\_many\_relation\_on\_build
+
+```python
+register_many_to_many_relation_on_build(new_model: Type["Model"], field: Type[ManyToManyField], field_name: str) -> None
+```
+
+Registers connection between through model and both sides of the m2m relation.
+Registration include also reverse relation side to be able to join both sides.
+
+Relation is registered by model name and relation field name to allow for multiple
+relations between two Models that needs to have different
+aliases for proper sql joins.
+
+By default relation name is a model.name.lower().
+
+**Arguments**:
+
+- `field_name (str)`: name of the relation key
+- `new_model (Model class)`: model on which m2m field is declared
+- `field (ManyToManyField class)`: relation field
+
+<a name="models.helpers.relations.expand_reverse_relationships"></a>
+#### expand\_reverse\_relationships
+
+```python
+expand_reverse_relationships(model: Type["Model"]) -> None
+```
+
+Iterates through model_fields of given model and verifies if all reverse
+relation have been populated on related models.
+
+If the reverse relation has not been set before it's set here.
+
+**Arguments**:
+
+- `model (Model class)`: model on which relation should be checked and registered
+
+<a name="models.helpers.relations.register_reverse_model_fields"></a>
+#### register\_reverse\_model\_fields
+
+```python
+register_reverse_model_fields(model: Type["Model"], child: Type["Model"], related_name: str, model_field: Type["ForeignKeyField"]) -> None
+```
+
+Registers reverse ForeignKey field on related model.
+By default it's name.lower()+'s' of the model on which relation is defined.
+
+But if the related_model name is provided it's registered with that name.
+Autogenerated reverse fields also set related_name to the original field name.
+
+**Arguments**:
+
+- `model (Model class)`: related model on which reverse field should be defined
+- `child (Model class)`: parent model with relation definition
+- `related_name (str)`: name by which reverse key should be registered
+- `model_field (relation Field)`: original relation ForeignKey field
+
+<a name="models.helpers.relations.register_relation_in_alias_manager"></a>
+#### register\_relation\_in\_alias\_manager
+
+```python
+register_relation_in_alias_manager(new_model: Type["Model"], field: Type[ForeignKeyField], field_name: str) -> None
+```
+
+Registers the relation (and reverse relation) in alias manager.
+The m2m relations require registration of through model between
+actual end models of the relation.
+
+Delegates the actual registration to:
+m2m - register_many_to_many_relation_on_build
+fk - register_relation_on_build
+
+**Arguments**:
+
+- `new_model (Model class)`: model on which relation field is declared
+- `field (ForeignKey or ManyToManyField class)`: relation field
+- `field_name (str)`: name of the relation key
+
+<a name="models.helpers.relations.verify_related_name_dont_duplicate"></a>
+#### verify\_related\_name\_dont\_duplicate
+
+```python
+verify_related_name_dont_duplicate(child: Type["Model"], parent_model: Type["Model"], related_name: str) -> None
+```
+
+Verifies whether the used related_name (regardless of the fact if user defined or
+auto generated) is already used on related model, but is connected with other model
+than the one that we connect right now.
+
+**Raises**:
+
+- `ModelDefinitionError`: if name is already used but lead to different related
+model
+
+**Arguments**:
+
+- `child (ormar.models.metaclass.ModelMetaclass)`: related Model class
+- `parent_model (ormar.models.metaclass.ModelMetaclass)`: parent Model class
+- `related_name ()`: 
+
+**Returns**:
+
+`(None)`: None
+
+<a name="models.helpers.relations.reverse_field_not_already_registered"></a>
+#### reverse\_field\_not\_already\_registered
+
+```python
+reverse_field_not_already_registered(child: Type["Model"], child_model_name: str, parent_model: Type["Model"]) -> bool
+```
+
+Checks if child is already registered in parents pydantic fields.
+
+**Raises**:
+
+- `ModelDefinitionError`: if related name is already used but lead to different
+related model
+
+**Arguments**:
+
+- `child (ormar.models.metaclass.ModelMetaclass)`: related Model class
+- `child_model_name (str)`: related_name of the child if provided
+- `parent_model (ormar.models.metaclass.ModelMetaclass)`: parent Model class
+
+**Returns**:
+
+`(bool)`: result of the check
+
--- a/docs/api/models/helpers/sqlalchemy.md
+++ b/docs/api/models/helpers/sqlalchemy.md
@ -0,0 +1,145 @@
+<a name="models.helpers.sqlalchemy"></a>
+# models.helpers.sqlalchemy
+
+<a name="models.helpers.sqlalchemy.adjust_through_many_to_many_model"></a>
+#### adjust\_through\_many\_to\_many\_model
+
+```python
+adjust_through_many_to_many_model(model: Type["Model"], child: Type["Model"], model_field: Type[ManyToManyField]) -> None
+```
+
+Registers m2m relation on through model.
+Sets ormar.ForeignKey from through model to both child and parent models.
+Sets sqlalchemy.ForeignKey to both child and parent models.
+Sets pydantic fields with child and parent model types.
+
+**Arguments**:
+
+- `model (Model class)`: model on which relation is declared
+- `child (Model class)`: model to which m2m relation leads
+- `model_field (ManyToManyField)`: relation field defined in parent model
+
+<a name="models.helpers.sqlalchemy.create_and_append_m2m_fk"></a>
+#### create\_and\_append\_m2m\_fk
+
+```python
+create_and_append_m2m_fk(model: Type["Model"], model_field: Type[ManyToManyField]) -> None
+```
+
+Registers sqlalchemy Column with sqlalchemy.ForeignKey leadning to the model.
+
+Newly created field is added to m2m relation through model Meta columns and table.
+
+**Arguments**:
+
+- `model (Model class)`: Model class to which FK should be created
+- `model_field (ManyToManyField field)`: field with ManyToMany relation
+
+<a name="models.helpers.sqlalchemy.check_pk_column_validity"></a>
+#### check\_pk\_column\_validity
+
+```python
+check_pk_column_validity(field_name: str, field: BaseField, pkname: Optional[str]) -> Optional[str]
+```
+
+Receives the field marked as primary key and verifies if the pkname
+was not already set (only one allowed per model) and if field is not marked
+as pydantic_only as it needs to be a database field.
+
+**Raises**:
+
+- `ModelDefintionError`: if pkname already set or field is pydantic_only
+
+**Arguments**:
+
+- `field_name (str)`: name of field
+- `field (BaseField)`: ormar.Field
+- `pkname (Optional[str])`: already set pkname
+
+**Returns**:
+
+`(str)`: name of the field that should be set as pkname
+
+<a name="models.helpers.sqlalchemy.sqlalchemy_columns_from_model_fields"></a>
+#### sqlalchemy\_columns\_from\_model\_fields
+
+```python
+sqlalchemy_columns_from_model_fields(model_fields: Dict, new_model: Type["Model"]) -> Tuple[Optional[str], List[sqlalchemy.Column]]
+```
+
+Iterates over declared on Model model fields and extracts fields that
+should be treated as database fields.
+
+If the model is empty it sets mandatory id field as primary key
+(used in through models in m2m relations).
+
+Triggers a validation of relation_names in relation fields. If multiple fields
+are leading to the same related model only one can have empty related_name param.
+Also related_names have to be unique.
+
+Trigger validation of primary_key - only one and required pk can be set,
+cannot be pydantic_only.
+
+Append fields to columns if it's not pydantic_only,
+virtual ForeignKey or ManyToMany field.
+
+**Raises**:
+
+- `ModelDefinitionError`: if validation of related_names fail,
+or pkname validation fails.
+
+**Arguments**:
+
+- `model_fields (Dict[str, ormar.Field])`: dictionary of declared ormar model fields
+- `new_model (Model class)`: 
+
+**Returns**:
+
+`(Tuple[Optional[str], List[sqlalchemy.Column]])`: pkname, list of sqlalchemy columns
+
+<a name="models.helpers.sqlalchemy.populate_meta_tablename_columns_and_pk"></a>
+#### populate\_meta\_tablename\_columns\_and\_pk
+
+```python
+populate_meta_tablename_columns_and_pk(name: str, new_model: Type["Model"]) -> Type["Model"]
+```
+
+Sets Model tablename if it's not already set in Meta.
+Default tablename if not present is class name lower + s (i.e. Bed becomes -> beds)
+
+Checks if Model's Meta have pkname and columns set.
+If not calls the sqlalchemy_columns_from_model_fields to populate
+columns from ormar.fields definitions.
+
+**Raises**:
+
+- `ModelDefinitionError`: if pkname is not present raises ModelDefinitionError.
+Each model has to have pk.
+
+**Arguments**:
+
+- `name (str)`: name of the current Model
+- `new_model (ormar.models.metaclass.ModelMetaclass)`: currently constructed Model
+
+**Returns**:
+
+`(ormar.models.metaclass.ModelMetaclass)`: Model with populated pkname and columns in Meta
+
+<a name="models.helpers.sqlalchemy.populate_meta_sqlalchemy_table_if_required"></a>
+#### populate\_meta\_sqlalchemy\_table\_if\_required
+
+```python
+populate_meta_sqlalchemy_table_if_required(meta: "ModelMeta") -> None
+```
+
+Constructs sqlalchemy table out of columns and parameters set on Meta class.
+It populates name, metadata, columns and constraints.
+
+**Arguments**:
+
+- `meta (Model class Meta)`: Meta class of the Model without sqlalchemy table constructed
+
+**Returns**:
+
+`(Model class)`: class with populated Meta.table
+
--- a/docs/api/models/mixins/alias-mixin.md
+++ b/docs/api/models/mixins/alias-mixin.md
@ -0,0 +1,90 @@
+<a name="models.mixins.alias_mixin"></a>
+# models.mixins.alias\_mixin
+
+<a name="models.mixins.alias_mixin.AliasMixin"></a>
+## AliasMixin Objects
+
+```python
+class AliasMixin()
+```
+
+Used to translate field names into database column names.
+
+<a name="models.mixins.alias_mixin.AliasMixin.get_column_alias"></a>
+#### get\_column\_alias
+
+```python
+ | @classmethod
+ | get_column_alias(cls, field_name: str) -> str
+```
+
+Returns db alias (column name in db) for given ormar field.
+For fields without alias field name is returned.
+
+**Arguments**:
+
+- `field_name (str)`: name of the field to get alias from
+
+**Returns**:
+
+`(str)`: alias (db name) if set, otherwise passed name
+
+<a name="models.mixins.alias_mixin.AliasMixin.get_column_name_from_alias"></a>
+#### get\_column\_name\_from\_alias
+
+```python
+ | @classmethod
+ | get_column_name_from_alias(cls, alias: str) -> str
+```
+
+Returns ormar field name for given db alias (column name in db).
+If field do not have alias it's returned as is.
+
+**Arguments**:
+
+- `alias (str)`: 
+
+**Returns**:
+
+`(str)`: field name if set, otherwise passed alias (db name)
+
+<a name="models.mixins.alias_mixin.AliasMixin.translate_columns_to_aliases"></a>
+#### translate\_columns\_to\_aliases
+
+```python
+ | @classmethod
+ | translate_columns_to_aliases(cls, new_kwargs: Dict) -> Dict
+```
+
+Translates dictionary of model fields changing field names into aliases.
+If field has no alias the field name remains intact.
+Only fields present in the dictionary are translated.
+
+**Arguments**:
+
+- `new_kwargs (Dict)`: dict with fields names and their values
+
+**Returns**:
+
+`(Dict)`: dict with aliases and their values
+
+<a name="models.mixins.alias_mixin.AliasMixin.translate_aliases_to_columns"></a>
+#### translate\_aliases\_to\_columns
+
+```python
+ | @classmethod
+ | translate_aliases_to_columns(cls, new_kwargs: Dict) -> Dict
+```
+
+Translates dictionary of model fields changing aliases into field names.
+If field has no alias the alias is already a field name.
+Only fields present in the dictionary are translated.
+
+**Arguments**:
+
+- `new_kwargs (Dict)`: dict with aliases and their values
+
+**Returns**:
+
+`(Dict)`: dict with fields names and their values
+
--- a/docs/api/models/mixins/excludable-mixin.md
+++ b/docs/api/models/mixins/excludable-mixin.md
@ -0,0 +1,206 @@
+<a name="models.mixins.excludable_mixin"></a>
+# models.mixins.excludable\_mixin
+
+<a name="models.mixins.excludable_mixin.ExcludableMixin"></a>
+## ExcludableMixin Objects
+
+```python
+class ExcludableMixin(RelationMixin)
+```
+
+Used to include/exclude given set of fields on models during load and dict() calls.
+
+<a name="models.mixins.excludable_mixin.ExcludableMixin.get_child"></a>
+#### get\_child
+
+```python
+ | @staticmethod
+ | get_child(items: Union[Set, Dict, None], key: str = None) -> Union[Set, Dict, None]
+```
+
+Used to get nested dictionaries keys if they exists otherwise returns
+passed items.
+
+**Arguments**:
+
+- `items (Union[Set, Dict, None])`: bag of items to include or exclude
+- `key (str)`: name of the child to extract
+
+**Returns**:
+
+`(Union[Set, Dict, None])`: child extracted from items if exists
+
+<a name="models.mixins.excludable_mixin.ExcludableMixin.get_excluded"></a>
+#### get\_excluded
+
+```python
+ | @staticmethod
+ | get_excluded(exclude: Union[Set, Dict, None], key: str = None) -> Union[Set, Dict, None]
+```
+
+Proxy to ExcludableMixin.get_child for exclusions.
+
+**Arguments**:
+
+- `exclude (Union[Set, Dict, None])`: bag of items to exclude
+- `key (str)`: name of the child to extract
+
+**Returns**:
+
+`(Union[Set, Dict, None])`: child extracted from items if exists
+
+<a name="models.mixins.excludable_mixin.ExcludableMixin.get_included"></a>
+#### get\_included
+
+```python
+ | @staticmethod
+ | get_included(include: Union[Set, Dict, None], key: str = None) -> Union[Set, Dict, None]
+```
+
+Proxy to ExcludableMixin.get_child for inclusions.
+
+**Arguments**:
+
+- `include (Union[Set, Dict, None])`: bag of items to include
+- `key (str)`: name of the child to extract
+
+**Returns**:
+
+`(Union[Set, Dict, None])`: child extracted from items if exists
+
+<a name="models.mixins.excludable_mixin.ExcludableMixin.is_excluded"></a>
+#### is\_excluded
+
+```python
+ | @staticmethod
+ | is_excluded(exclude: Union[Set, Dict, None], key: str = None) -> bool
+```
+
+Checks if given key should be excluded on model/ dict.
+
+**Arguments**:
+
+- `exclude (Union[Set, Dict, None])`: bag of items to exclude
+- `key (str)`: name of the child to extract
+
+**Returns**:
+
+`(Union[Set, Dict, None])`: child extracted from items if exists
+
+<a name="models.mixins.excludable_mixin.ExcludableMixin.is_included"></a>
+#### is\_included
+
+```python
+ | @staticmethod
+ | is_included(include: Union[Set, Dict, None], key: str = None) -> bool
+```
+
+Checks if given key should be included on model/ dict.
+
+**Arguments**:
+
+- `include (Union[Set, Dict, None])`: bag of items to include
+- `key (str)`: name of the child to extract
+
+**Returns**:
+
+`(Union[Set, Dict, None])`: child extracted from items if exists
+
+<a name="models.mixins.excludable_mixin.ExcludableMixin._populate_pk_column"></a>
+#### \_populate\_pk\_column
+
+```python
+ | @staticmethod
+ | _populate_pk_column(model: Type["Model"], columns: List[str], use_alias: bool = False) -> List[str]
+```
+
+Adds primary key column/alias (depends on use_alias flag) to list of
+column names that are selected.
+
+**Arguments**:
+
+- `model (Type["Model"])`: model on columns are selected
+- `columns (List[str])`: list of columns names
+- `use_alias (bool)`: flag to set if aliases or field names should be used
+
+**Returns**:
+
+`(List[str])`: list of columns names with pk column in it
+
+<a name="models.mixins.excludable_mixin.ExcludableMixin.own_table_columns"></a>
+#### own\_table\_columns
+
+```python
+ | @classmethod
+ | own_table_columns(cls, model: Type["Model"], fields: Optional[Union[Set, Dict]], exclude_fields: Optional[Union[Set, Dict]], use_alias: bool = False) -> List[str]
+```
+
+Returns list of aliases or field names for given model.
+Aliases/names switch is use_alias flag.
+
+If provided only fields included in fields will be returned.
+If provided fields in exclude_fields will be excluded in return.
+
+Primary key field is always added and cannot be excluded (will be added anyway).
+
+**Arguments**:
+
+- `model (Type["Model"])`: model on columns are selected
+- `fields (Optional[Union[Set, Dict]])`: set/dict of fields to include
+- `exclude_fields (Optional[Union[Set, Dict]])`: set/dict of fields to exclude
+- `use_alias (bool)`: flag if aliases or field names should be used
+
+**Returns**:
+
+`(List[str])`: list of column field names or aliases
+
+<a name="models.mixins.excludable_mixin.ExcludableMixin._update_excluded_with_related_not_required"></a>
+#### \_update\_excluded\_with\_related\_not\_required
+
+```python
+ | @classmethod
+ | _update_excluded_with_related_not_required(cls, exclude: Union["AbstractSetIntStr", "MappingIntStrAny", None], nested: bool = False) -> Union[Set, Dict]
+```
+
+Used during generation of the dict().
+To avoid cyclical references and max recurrence limit nested models have to
+exclude related models that are not mandatory.
+
+For a main model (not nested) only nullable related field names are added to
+exclusion, for nested models all related models are excluded.
+
+**Arguments**:
+
+- `exclude (Union[Set, Dict, None])`: set/dict with fields to exclude
+- `nested (bool)`: flag setting nested models (child of previous one, not main one)
+
+**Returns**:
+
+`(Union[Set, Dict])`: set or dict with excluded fields added.
+
+<a name="models.mixins.excludable_mixin.ExcludableMixin.get_names_to_exclude"></a>
+#### get\_names\_to\_exclude
+
+```python
+ | @classmethod
+ | get_names_to_exclude(cls, fields: Optional[Union[Dict, Set]] = None, exclude_fields: Optional[Union[Dict, Set]] = None) -> Set
+```
+
+Returns a set of models field names that should be explicitly excluded
+during model initialization.
+
+Those fields will be set to None to avoid ormar/pydantic setting default
+values on them. They should be returned as None in any case.
+
+Used in parsing data from database rows that construct Models by initializing
+them with dicts constructed from those db rows.
+
+**Arguments**:
+
+- `fields (Optional[Union[Set, Dict]])`: set/dict of fields to include
+- `exclude_fields (Optional[Union[Set, Dict]])`: set/dict of fields to exclude
+
+**Returns**:
+
+`(Set)`: set of field names that should be excluded
+
--- a/docs/api/models/mixins/merge-model-mixin.md
+++ b/docs/api/models/mixins/merge-model-mixin.md
@ -0,0 +1,60 @@
+<a name="models.mixins.merge_mixin"></a>
+# models.mixins.merge\_mixin
+
+<a name="models.mixins.merge_mixin.MergeModelMixin"></a>
+## MergeModelMixin Objects
+
+```python
+class MergeModelMixin()
+```
+
+Used to merge models instances returned by database,
+but already initialized to ormar Models.keys
+
+Models can duplicate during joins when parent model has multiple child rows,
+in the end all parent (main) models should be unique.
+
+<a name="models.mixins.merge_mixin.MergeModelMixin.merge_instances_list"></a>
+#### merge\_instances\_list
+
+```python
+ | @classmethod
+ | merge_instances_list(cls, result_rows: Sequence["Model"]) -> Sequence["Model"]
+```
+
+Merges a list of models into list of unique models.
+
+Models can duplicate during joins when parent model has multiple child rows,
+in the end all parent (main) models should be unique.
+
+**Arguments**:
+
+- `result_rows (List["Model"])`: list of already initialized Models with child models
+populated, each instance is one row in db and some models can duplicate
+
+**Returns**:
+
+`(List["Model"])`: list of merged models where each main model is unique
+
+<a name="models.mixins.merge_mixin.MergeModelMixin.merge_two_instances"></a>
+#### merge\_two\_instances
+
+```python
+ | @classmethod
+ | merge_two_instances(cls, one: "Model", other: "Model") -> "Model"
+```
+
+Merges current (other) Model and previous one (one) and returns the current
+Model instance with data merged from previous one.
+
+If needed it's calling itself recurrently and merges also children models.
+
+**Arguments**:
+
+- `one (Model)`: previous model instance
+- `other (Model)`: current model instance
+
+**Returns**:
+
+`(Model)`: current Model instance with data merged from previous one.
+
--- a/docs/api/models/mixins/prefetch-query-mixin.md
+++ b/docs/api/models/mixins/prefetch-query-mixin.md
@ -0,0 +1,100 @@
+<a name="models.mixins.prefetch_mixin"></a>
+# models.mixins.prefetch\_mixin
+
+<a name="models.mixins.prefetch_mixin.PrefetchQueryMixin"></a>
+## PrefetchQueryMixin Objects
+
+```python
+class PrefetchQueryMixin(RelationMixin)
+```
+
+Used in PrefetchQuery to extract ids and names of models to prefetch.
+
+<a name="models.mixins.prefetch_mixin.PrefetchQueryMixin.get_clause_target_and_filter_column_name"></a>
+#### get\_clause\_target\_and\_filter\_column\_name
+
+```python
+ | @staticmethod
+ | get_clause_target_and_filter_column_name(parent_model: Type["Model"], target_model: Type["Model"], reverse: bool, related: str) -> Tuple[Type["Model"], str]
+```
+
+Returns Model on which query clause should be performed and name of the column.
+
+**Arguments**:
+
+- `parent_model (Type[Model])`: related model that the relation lead to
+- `target_model (Type[Model])`: model on which query should be perfomed
+- `reverse (bool)`: flag if the relation is reverse
+- `related (str)`: name of the relation field
+
+**Returns**:
+
+`(Tuple[Type[Model], str])`: Model on which query clause should be performed and name of the column
+
+<a name="models.mixins.prefetch_mixin.PrefetchQueryMixin.get_column_name_for_id_extraction"></a>
+#### get\_column\_name\_for\_id\_extraction
+
+```python
+ | @staticmethod
+ | get_column_name_for_id_extraction(parent_model: Type["Model"], reverse: bool, related: str, use_raw: bool) -> str
+```
+
+Returns name of the column that should be used to extract ids from model.
+Depending on the relation side it's either primary key column of parent model
+or field name specified by related parameter.
+
+**Arguments**:
+
+- `parent_model (Type[Model])`: model from which id column should be extracted
+- `reverse (bool)`: flag if the relation is reverse
+- `related (str)`: name of the relation field
+- `use_raw (bool)`: flag if aliases or field names should be used
+
+**Returns**:
+
+`()`: 
+
+<a name="models.mixins.prefetch_mixin.PrefetchQueryMixin.get_related_field_name"></a>
+#### get\_related\_field\_name
+
+```python
+ | @classmethod
+ | get_related_field_name(cls, target_field: Type["BaseField"]) -> str
+```
+
+Returns name of the relation field that should be used in prefetch query.
+This field is later used to register relation in prefetch query,
+populate relations dict, and populate nested model in prefetch query.
+
+**Arguments**:
+
+- `target_field (Type[BaseField])`: relation field that should be used in prefetch
+
+**Returns**:
+
+`(str)`: name of the field
+
+<a name="models.mixins.prefetch_mixin.PrefetchQueryMixin.get_filtered_names_to_extract"></a>
+#### get\_filtered\_names\_to\_extract
+
+```python
+ | @classmethod
+ | get_filtered_names_to_extract(cls, prefetch_dict: Dict) -> List
+```
+
+Returns list of related fields names that should be followed to prefetch related
+models from.
+
+List of models is translated into dict to assure each model is extracted only
+once in one query, that's why this function accepts prefetch_dict not list.
+
+Only relations from current model are returned.
+
+**Arguments**:
+
+- `prefetch_dict (Dict)`: dictionary of fields to extract
+
+**Returns**:
+
+`(List)`: list of fields names to extract
+
--- a/docs/api/models/mixins/relation-mixin.md
+++ b/docs/api/models/mixins/relation-mixin.md
@ -0,0 +1,93 @@
+<a name="models.mixins.relation_mixin"></a>
+# models.mixins.relation\_mixin
+
+<a name="models.mixins.relation_mixin.RelationMixin"></a>
+## RelationMixin Objects
+
+```python
+class RelationMixin()
+```
+
+Used to return relation fields/names etc. from given model
+
+<a name="models.mixins.relation_mixin.RelationMixin.extract_db_own_fields"></a>
+#### extract\_db\_own\_fields
+
+```python
+ | @classmethod
+ | extract_db_own_fields(cls) -> Set
+```
+
+Returns only fields that are stored in the own database table, exclude all
+related fields.
+
+**Returns**:
+
+`(Set)`: set of model fields with relation fields excluded
+
+<a name="models.mixins.relation_mixin.RelationMixin.extract_related_fields"></a>
+#### extract\_related\_fields
+
+```python
+ | @classmethod
+ | extract_related_fields(cls) -> List
+```
+
+Returns List of ormar Fields for all relations declared on a model.
+List is cached in cls._related_fields for quicker access.
+
+**Returns**:
+
+`(List)`: list of related fields
+
+<a name="models.mixins.relation_mixin.RelationMixin.extract_related_names"></a>
+#### extract\_related\_names
+
+```python
+ | @classmethod
+ | extract_related_names(cls) -> Set
+```
+
+Returns List of fields names for all relations declared on a model.
+List is cached in cls._related_names for quicker access.
+
+**Returns**:
+
+`(List)`: list of related fields names
+
+<a name="models.mixins.relation_mixin.RelationMixin._extract_db_related_names"></a>
+#### \_extract\_db\_related\_names
+
+```python
+ | @classmethod
+ | _extract_db_related_names(cls) -> Set
+```
+
+Returns only fields that are stored in the own database table, exclude
+related fields that are not stored as foreign keys on given model.
+
+**Returns**:
+
+`(Set)`: set of model fields with non fk relation fields excluded
+
+<a name="models.mixins.relation_mixin.RelationMixin._exclude_related_names_not_required"></a>
+#### \_exclude\_related\_names\_not\_required
+
+```python
+ | @classmethod
+ | _exclude_related_names_not_required(cls, nested: bool = False) -> Set
+```
+
+Returns a set of non mandatory related models field names.
+
+For a main model (not nested) only nullable related field names are returned,
+for nested models all related models are returned.
+
+**Arguments**:
+
+- `nested (bool)`: flag setting nested models (child of previous one, not main one)
+
+**Returns**:
+
+`(Set)`: set of non mandatory related fields
+
--- a/docs/api/models/mixins/save-prepare-mixin.md
+++ b/docs/api/models/mixins/save-prepare-mixin.md
@ -0,0 +1,93 @@
+<a name="models.mixins.save_mixin"></a>
+# models.mixins.save\_mixin
+
+<a name="models.mixins.save_mixin.SavePrepareMixin"></a>
+## SavePrepareMixin Objects
+
+```python
+class SavePrepareMixin(RelationMixin,  AliasMixin)
+```
+
+Used to prepare models to be saved in database
+
+<a name="models.mixins.save_mixin.SavePrepareMixin.prepare_model_to_save"></a>
+#### prepare\_model\_to\_save
+
+```python
+ | @classmethod
+ | prepare_model_to_save(cls, new_kwargs: dict) -> dict
+```
+
+Combines all preparation methods before saving.
+Removes primary key for if it's nullable or autoincrement pk field,
+and it's set to None.
+Substitute related models with their primary key values as fk column.
+Populates the default values for field with default set and no value.
+Translate columns into aliases (db names).
+
+**Arguments**:
+
+- `new_kwargs (Dict[str, str])`: dictionary of model that is about to be saved
+
+**Returns**:
+
+`(Dict[str, str])`: dictionary of model that is about to be saved
+
+<a name="models.mixins.save_mixin.SavePrepareMixin._remove_pk_from_kwargs"></a>
+#### \_remove\_pk\_from\_kwargs
+
+```python
+ | @classmethod
+ | _remove_pk_from_kwargs(cls, new_kwargs: dict) -> dict
+```
+
+Removes primary key for if it's nullable or autoincrement pk field,
+and it's set to None.
+
+**Arguments**:
+
+- `new_kwargs (Dict[str, str])`: dictionary of model that is about to be saved
+
+**Returns**:
+
+`(Dict[str, str])`: dictionary of model that is about to be saved
+
+<a name="models.mixins.save_mixin.SavePrepareMixin.substitute_models_with_pks"></a>
+#### substitute\_models\_with\_pks
+
+```python
+ | @classmethod
+ | substitute_models_with_pks(cls, model_dict: Dict) -> Dict
+```
+
+Receives dictionary of model that is about to be saved and changes all related
+models that are stored as foreign keys to their fk value.
+
+**Arguments**:
+
+- `model_dict (Dict)`: dictionary of model that is about to be saved
+
+**Returns**:
+
+`(Dict)`: dictionary of model that is about to be saved
+
+<a name="models.mixins.save_mixin.SavePrepareMixin.populate_default_values"></a>
+#### populate\_default\_values
+
+```python
+ | @classmethod
+ | populate_default_values(cls, new_kwargs: Dict) -> Dict
+```
+
+Receives dictionary of model that is about to be saved and populates the default
+value on the fields that have the default value set, but no actual value was
+passed by the user.
+
+**Arguments**:
+
+- `new_kwargs (Dict)`: dictionary of model that is about to be saved
+
+**Returns**:
+
+`(Dict)`: dictionary of model that is about to be saved
+
--- a/docs/api/models/model-metaclass.md
+++ b/docs/api/models/model-metaclass.md
@ -0,0 +1,340 @@
+<a name="models.metaclass"></a>
+# models.metaclass
+
+<a name="models.metaclass.PARSED_FIELDS_KEY"></a>
+#### PARSED\_FIELDS\_KEY
+
+<a name="models.metaclass.CONFIG_KEY"></a>
+#### CONFIG\_KEY
+
+<a name="models.metaclass.ModelMeta"></a>
+## ModelMeta Objects
+
+```python
+class ModelMeta()
+```
+
+Class used for type hinting.
+Users can subclass this one for convenience but it's not required.
+The only requirement is that ormar.Model has to have inner class with name Meta.
+
+<a name="models.metaclass.ModelMeta.tablename"></a>
+#### tablename
+
+<a name="models.metaclass.ModelMeta.table"></a>
+#### table
+
+<a name="models.metaclass.ModelMeta.metadata"></a>
+#### metadata
+
+<a name="models.metaclass.ModelMeta.database"></a>
+#### database
+
+<a name="models.metaclass.ModelMeta.columns"></a>
+#### columns
+
+<a name="models.metaclass.ModelMeta.constraints"></a>
+#### constraints
+
+<a name="models.metaclass.ModelMeta.pkname"></a>
+#### pkname
+
+<a name="models.metaclass.ModelMeta.model_fields"></a>
+#### model\_fields
+
+<a name="models.metaclass.ModelMeta.alias_manager"></a>
+#### alias\_manager
+
+<a name="models.metaclass.ModelMeta.property_fields"></a>
+#### property\_fields
+
+<a name="models.metaclass.ModelMeta.signals"></a>
+#### signals
+
+<a name="models.metaclass.ModelMeta.abstract"></a>
+#### abstract
+
+<a name="models.metaclass.check_if_field_has_choices"></a>
+#### check\_if\_field\_has\_choices
+
+```python
+check_if_field_has_choices(field: Type[BaseField]) -> bool
+```
+
+Checks if given field has choices populated.
+A if it has one, a validator for this field needs to be attached.
+
+**Arguments**:
+
+- `field (BaseField)`: ormar field to check
+
+**Returns**:
+
+`(bool)`: result of the check
+
+<a name="models.metaclass.choices_validator"></a>
+#### choices\_validator
+
+```python
+choices_validator(cls: Type["Model"], values: Dict[str, Any]) -> Dict[str, Any]
+```
+
+Validator that is attached to pydantic model pre root validators.
+Validator checks if field value is in field.choices list.
+
+**Raises**:
+
+- `ValueError`: if field value is outside of allowed choices.
+
+**Arguments**:
+
+- `cls (Model class)`: constructed class
+- `values (Dict[str, Any])`: dictionary of field values (pydantic side)
+
+**Returns**:
+
+`(Dict[str, Any])`: values if pass validation, otherwise exception is raised
+
+<a name="models.metaclass.populate_choices_validators"></a>
+#### populate\_choices\_validators
+
+```python
+populate_choices_validators(model: Type["Model"]) -> None
+```
+
+Checks if Model has any fields with choices set.
+If yes it adds choices validation into pre root validators.
+
+**Arguments**:
+
+- `model (Model class)`: newly constructed Model
+
+<a name="models.metaclass.add_cached_properties"></a>
+#### add\_cached\_properties
+
+```python
+add_cached_properties(new_model: Type["Model"]) -> None
+```
+
+Sets cached properties for both pydantic and ormar models.
+
+Quick access fields are fields grabbed in getattribute to skip all checks.
+
+Related fields and names are populated to None as they can change later.
+When children models are constructed they can modify parent to register itself.
+
+All properties here are used as "cache" to not recalculate them constantly.
+
+**Arguments**:
+
+- `new_model (Model class)`: newly constructed Model
+
+<a name="models.metaclass.meta_field_not_set"></a>
+#### meta\_field\_not\_set
+
+```python
+meta_field_not_set(model: Type["Model"], field_name: str) -> bool
+```
+
+Checks if field with given name is already present in model.Meta.
+Then check if it's set to something truthful
+(in practice meaning not None, as it's non or ormar Field only).
+
+**Arguments**:
+
+- `model (Model class)`: newly constructed model
+- `field_name (str)`: name of the ormar field
+
+**Returns**:
+
+`(bool)`: result of the check
+
+<a name="models.metaclass.add_property_fields"></a>
+#### add\_property\_fields
+
+```python
+add_property_fields(new_model: Type["Model"], attrs: Dict) -> None
+```
+
+Checks class namespace for properties or functions with __property_field__.
+If attribute have __property_field__ it was decorated with @property_field.
+
+Functions like this are exposed in dict() (therefore also fastapi result).
+Names of property fields are cached for quicker access / extraction.
+
+**Arguments**:
+
+- `new_model (Model class)`: newly constructed model
+- `attrs (Dict[str, str])`: 
+
+<a name="models.metaclass.register_signals"></a>
+#### register\_signals
+
+```python
+register_signals(new_model: Type["Model"]) -> None
+```
+
+Registers on model's SignalEmmiter and sets pre defined signals.
+Predefined signals are (pre/post) + (save/update/delete).
+
+Signals are emitted in both model own methods and in selected queryset ones.
+
+**Arguments**:
+
+- `new_model (Model class)`: newly constructed model
+
+<a name="models.metaclass.update_attrs_and_fields"></a>
+#### update\_attrs\_and\_fields
+
+```python
+update_attrs_and_fields(attrs: Dict, new_attrs: Dict, model_fields: Dict, new_model_fields: Dict, new_fields: Set) -> Dict
+```
+
+Updates __annotations__, values of model fields (so pydantic FieldInfos)
+as well as model.Meta.model_fields definitions from parents.
+
+**Arguments**:
+
+- `attrs (Dict)`: new namespace for class being constructed
+- `new_attrs (Dict)`: part of the namespace extracted from parent class
+- `model_fields (Dict[str, BaseField])`: ormar fields in defined in current class
+- `new_model_fields (Dict[str, BaseField])`: ormar fields defined in parent classes
+- `new_fields (Set[str])`: set of new fields names
+
+<a name="models.metaclass.verify_constraint_names"></a>
+#### verify\_constraint\_names
+
+```python
+verify_constraint_names(base_class: "Model", model_fields: Dict, parent_value: List) -> None
+```
+
+Verifies if redefined fields that are overwritten in subclasses did not remove
+any name of the column that is used in constraint as it will fail in sqlalchemy
+Table creation.
+
+**Arguments**:
+
+- `base_class (Model or model parent class)`: one of the parent classes
+- `model_fields (Dict[str, BaseField])`: ormar fields in defined in current class
+- `parent_value (List)`: list of base class constraints
+
+<a name="models.metaclass.update_attrs_from_base_meta"></a>
+#### update\_attrs\_from\_base\_meta
+
+```python
+update_attrs_from_base_meta(base_class: "Model", attrs: Dict, model_fields: Dict) -> None
+```
+
+Updates Meta parameters in child from parent if needed.
+
+**Arguments**:
+
+- `base_class (Model or model parent class)`: one of the parent classes
+- `attrs (Dict)`: new namespace for class being constructed
+- `model_fields (Dict[str, BaseField])`: ormar fields in defined in current class
+
+<a name="models.metaclass.copy_data_from_parent_model"></a>
+#### copy\_data\_from\_parent\_model
+
+```python
+copy_data_from_parent_model(base_class: Type["Model"], curr_class: type, attrs: Dict, model_fields: Dict[
+        str, Union[Type[BaseField], Type[ForeignKeyField], Type[ManyToManyField]]
+    ]) -> Tuple[Dict, Dict]
+```
+
+Copy the key parameters [databse, metadata, property_fields and constraints]
+and fields from parent models. Overwrites them if needed.
+
+Only abstract classes can be subclassed.
+
+Since relation fields requires different related_name for different children
+
+
+**Raises**:
+
+- `ModelDefinitionError`: if non abstract model is subclassed
+
+**Arguments**:
+
+- `base_class (Model or model parent class)`: one of the parent classes
+- `curr_class (Model or model parent class)`: current constructed class
+- `attrs (Dict)`: new namespace for class being constructed
+- `model_fields (Dict[str, BaseField])`: ormar fields in defined in current class
+
+**Returns**:
+
+`(Tuple[Dict, Dict])`: updated attrs and model_fields
+
+<a name="models.metaclass.extract_from_parents_definition"></a>
+#### extract\_from\_parents\_definition
+
+```python
+extract_from_parents_definition(base_class: type, curr_class: type, attrs: Dict, model_fields: Dict[
+        str, Union[Type[BaseField], Type[ForeignKeyField], Type[ManyToManyField]]
+    ]) -> Tuple[Dict, Dict]
+```
+
+Extracts fields from base classes if they have valid oramr fields.
+
+If model was already parsed -> fields definitions need to be removed from class
+cause pydantic complains about field re-definition so after first child
+we need to extract from __parsed_fields__ not the class itself.
+
+If the class is parsed first time annotations and field definition is parsed
+from the class.__dict__.
+
+If the class is a ormar.Model it is skipped.
+
+**Arguments**:
+
+- `base_class (Model or model parent class)`: one of the parent classes
+- `curr_class (Model or model parent class)`: current constructed class
+- `attrs (Dict)`: new namespace for class being constructed
+- `model_fields (Dict[str, BaseField])`: ormar fields in defined in current class
+
+**Returns**:
+
+`(Tuple[Dict, Dict])`: updated attrs and model_fields
+
+<a name="models.metaclass.ModelMetaclass"></a>
+## ModelMetaclass Objects
+
+```python
+class ModelMetaclass(pydantic.main.ModelMetaclass)
+```
+
+<a name="models.metaclass.ModelMetaclass.__new__"></a>
+#### \_\_new\_\_
+
+```python
+ | __new__(mcs: "ModelMetaclass", name: str, bases: Any, attrs: dict) -> "ModelMetaclass"
+```
+
+Metaclass used by ormar Models that performs configuration
+and build of ormar Models.
+
+
+Sets pydantic configuration.
+Extract model_fields and convert them to pydantic FieldInfo,
+updates class namespace.
+
+Extracts settings and fields from parent classes.
+Fetches methods decorated with @property_field decorator
+to expose them later in dict().
+
+Construct parent pydantic Metaclass/ Model.
+
+If class has Meta class declared (so actual ormar Models) it also:
+
+* populate sqlalchemy columns, pkname and tables from model_fields
+* register reverse relationships on related models
+* registers all relations in alias manager that populates table_prefixes
+* exposes alias manager on each Model
+* creates QuerySet for each model and exposes it on a class
+
+**Arguments**:
+
+- `name (str)`: name of current class
+- `bases (Tuple)`: base classes
+- `attrs (Dict)`: class namespace
+
--- a/docs/api/models/model-table-proxy.md
+++ b/docs/api/models/model-table-proxy.md
@ -0,0 +1,14 @@
+<a name="models.modelproxy"></a>
+# models.modelproxy
+
+<a name="models.modelproxy.ModelTableProxy"></a>
+## ModelTableProxy Objects
+
+```python
+class ModelTableProxy(
+    PrefetchQueryMixin,  MergeModelMixin,  SavePrepareMixin,  ExcludableMixin)
+```
+
+Used to combine all mixins with different set of functionalities.
+One of the bases of the ormar Model class.
+
--- a/docs/api/models/model.md
+++ b/docs/api/models/model.md
@ -0,0 +1,323 @@
+<a name="models.model"></a>
+# models.model
+
+<a name="models.model.group_related_list"></a>
+#### group\_related\_list
+
+```python
+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
+
+<a name="models.model.T"></a>
+#### T
+
+<a name="models.model.Model"></a>
+## Model Objects
+
+```python
+class Model(NewBaseModel)
+```
+
+<a name="models.model.Model.__abstract__"></a>
+#### \_\_abstract\_\_
+
+<a name="models.model.Model.__repr__"></a>
+#### \_\_repr\_\_
+
+```python
+ | __repr__() -> str
+```
+
+<a name="models.model.Model.from_row"></a>
+#### from\_row
+
+```python
+ | @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
+
+<a name="models.model.Model.populate_nested_models_from_row"></a>
+#### populate\_nested\_models\_from\_row
+
+```python
+ | @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
+
+<a name="models.model.Model.extract_prefixed_table_columns"></a>
+#### extract\_prefixed\_table\_columns
+
+```python
+ | @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
+
+<a name="models.model.Model.upsert"></a>
+#### upsert
+
+```python
+ | 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
+
+<a name="models.model.Model.save"></a>
+#### save
+
+```python
+ | 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
+
+<a name="models.model.Model.save_related"></a>
+#### save\_related
+
+```python
+ | 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
+
+<a name="models.model.Model._update_and_follow"></a>
+#### \_update\_and\_follow
+
+```python
+ | @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
+
+<a name="models.model.Model.update"></a>
+#### update
+
+```python
+ | 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 will throw ModelPersistenceError
+
+**Arguments**:
+
+- `kwargs (Any)`: list of fields to update as field=value pairs
+
+**Returns**:
+
+`(Model)`: updated Model
+
+<a name="models.model.Model.delete"></a>
+#### delete
+
+```python
+ | 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)
+
+<a name="models.model.Model.load"></a>
+#### load
+
+```python
+ | 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 the NoMatch exception is raised.
+
+**Returns**:
+
+`(Model)`: reloaded Model
+
--- a/docs/api/models/new-basemodel.md
+++ b/docs/api/models/new-basemodel.md
@ -0,0 +1,512 @@
+<a name="models.newbasemodel"></a>
+# models.newbasemodel
+
+<a name="models.newbasemodel.NewBaseModel"></a>
+## NewBaseModel Objects
+
+```python
+class NewBaseModel(pydantic.BaseModel,  ModelTableProxy, metaclass=ModelMetaclass)
+```
+
+Main base class of ormar Model.
+Inherits from pydantic BaseModel and has all mixins combined in ModelTableProxy.
+Constructed with ModelMetaclass which in turn also inherits pydantic metaclass.
+
+Abstracts away all internals and helper functions, so final Model class has only
+the logic concerned with database connection and data persistance.
+
+<a name="models.newbasemodel.NewBaseModel.__slots__"></a>
+#### \_\_slots\_\_
+
+<a name="models.newbasemodel.NewBaseModel.__init__"></a>
+#### \_\_init\_\_
+
+```python
+ | __init__(*args: Any, **kwargs: Any) -> None
+```
+
+Initializer that creates a new ormar Model that is also pydantic Model at the
+same time.
+
+Passed keyword arguments can be only field names and their corresponding values
+as those will be passed to pydantic validation that will complain if extra
+params are passed.
+
+If relations are defined each relation is expanded and children models are also
+initialized and validated. Relation from both sides is registered so you can
+access related models from both sides.
+
+Json fields are automatically loaded/dumped if needed.
+
+Models marked as abstract=True in internal Meta class cannot be initialized.
+
+Accepts also special __pk_only__ flag that indicates that Model is constructed
+only with primary key value (so no other fields, it's a child model on other
+Model), that causes skipping the validation, that's the only case when the
+validation can be skipped.
+
+Accepts also special __excluded__ parameter that contains a set of fields that
+should be explicitly set to None, as otherwise pydantic will try to populate
+them with their default values if default is set.
+
+**Raises**:
+
+- `ModelError`: if abstract model is initialized or unknown field is passed
+
+**Arguments**:
+
+- `args (Any)`: ignored args
+- `kwargs (Any)`: keyword arguments - all fields values and some special params
+
+<a name="models.newbasemodel.NewBaseModel.__setattr__"></a>
+#### \_\_setattr\_\_
+
+```python
+ | __setattr__(name: str, value: Any) -> None
+```
+
+Overwrites setattr in object to allow for special behaviour of certain params.
+
+Parameter "pk" is translated into actual primary key field name.
+
+Relations are expanded (child model constructed if needed) and registered on
+both ends of the relation. The related models are handled by RelationshipManager
+exposed at _orm param.
+
+Json fields converted if needed.
+
+Setting pk, foreign key value or any other field value sets Model save status
+to False. Setting a reverse relation or many to many relation does not as it
+does not modify the state of the model (but related model or through model).
+
+To short circuit all checks and expansions the set of attribute names present
+on each model is gathered into _quick_access_fields that is looked first and
+if field is in this set the object setattr is called directly.
+
+**Arguments**:
+
+- `name (str)`: name of the attribute to set
+- `value (Any)`: value of the attribute to set
+
+**Returns**:
+
+`(None)`: None
+
+<a name="models.newbasemodel.NewBaseModel.__getattribute__"></a>
+#### \_\_getattribute\_\_
+
+```python
+ | __getattribute__(item: str) -> Any
+```
+
+Because we need to overwrite getting the attribute by ormar instead of pydantic
+as well as returning related models and not the value stored on the model the
+__getattribute__ needs to be used not __getattr__.
+
+It's used to access all attributes so it can be a big overhead that's why a
+number of short circuits is used.
+
+To short circuit all checks and expansions the set of attribute names present
+on each model is gathered into _quick_access_fields that is looked first and
+if field is in this set the object setattr is called directly.
+
+To avoid recursion object's getattribute is used to actually get the attribute
+value from the model after the checks.
+
+Even the function calls are constructed with objects functions.
+
+Parameter "pk" is translated into actual primary key field name.
+
+Relations are returned so the actual related model is returned and not current
+model's field. The related models are handled by RelationshipManager exposed
+at _orm param.
+
+Json fields are converted if needed.
+
+**Arguments**:
+
+- `item (str)`: name of the attribute to retrieve
+
+**Returns**:
+
+`(Any)`: value of the attribute
+
+<a name="models.newbasemodel.NewBaseModel._extract_related_model_instead_of_field"></a>
+#### \_extract\_related\_model\_instead\_of\_field
+
+```python
+ | _extract_related_model_instead_of_field(item: str) -> Optional[Union["T", Sequence["T"]]]
+```
+
+Retrieves the related model/models from RelationshipManager.
+
+**Arguments**:
+
+- `item (str)`: name of the relation
+
+**Returns**:
+
+`(Optional[Union[Model, List[Model]]])`: related model, list of related models or None
+
+<a name="models.newbasemodel.NewBaseModel.__eq__"></a>
+#### \_\_eq\_\_
+
+```python
+ | __eq__(other: object) -> bool
+```
+
+Compares other model to this model. when == is called.
+
+**Arguments**:
+
+- `other (object)`: other model to compare
+
+**Returns**:
+
+`(bool)`: result of comparison
+
+<a name="models.newbasemodel.NewBaseModel.__same__"></a>
+#### \_\_same\_\_
+
+```python
+ | __same__(other: "NewBaseModel") -> bool
+```
+
+Used by __eq__, compares other model to this model.
+Compares:
+* _orm_ids,
+* primary key values if it's set
+* dictionary of own fields (excluding relations)
+
+**Arguments**:
+
+- `other (NewBaseModel)`: model to compare to
+
+**Returns**:
+
+`(bool)`: result of comparison
+
+<a name="models.newbasemodel.NewBaseModel.get_name"></a>
+#### get\_name
+
+```python
+ | @classmethod
+ | get_name(cls, lower: bool = True) -> str
+```
+
+Returns name of the Model class, by default lowercase.
+
+**Arguments**:
+
+- `lower (bool)`: flag if name should be set to lowercase
+
+**Returns**:
+
+`(str)`: name of the model
+
+<a name="models.newbasemodel.NewBaseModel.pk_column"></a>
+#### pk\_column
+
+```python
+ | @property
+ | pk_column() -> sqlalchemy.Column
+```
+
+Retrieves primary key sqlalchemy column from models Meta.table.
+Each model has to have primary key.
+Only one primary key column is allowed.
+
+**Returns**:
+
+`(sqlalchemy.Column)`: primary key sqlalchemy column
+
+<a name="models.newbasemodel.NewBaseModel.saved"></a>
+#### saved
+
+```python
+ | @property
+ | saved() -> bool
+```
+
+Saved status of the model. Changed by setattr and loading from db
+
+<a name="models.newbasemodel.NewBaseModel.signals"></a>
+#### signals
+
+```python
+ | @property
+ | signals() -> "SignalEmitter"
+```
+
+Exposes signals from model Meta
+
+<a name="models.newbasemodel.NewBaseModel.pk_type"></a>
+#### pk\_type
+
+```python
+ | @classmethod
+ | pk_type(cls) -> Any
+```
+
+Shortcut to models primary key field type
+
+<a name="models.newbasemodel.NewBaseModel.db_backend_name"></a>
+#### db\_backend\_name
+
+```python
+ | @classmethod
+ | db_backend_name(cls) -> str
+```
+
+Shortcut to database dialect,
+cause some dialect require different treatment
+
+<a name="models.newbasemodel.NewBaseModel.remove"></a>
+#### remove
+
+```python
+ | remove(parent: "T", name: str) -> None
+```
+
+Removes child from relation with given name in RelationshipManager
+
+<a name="models.newbasemodel.NewBaseModel.set_save_status"></a>
+#### set\_save\_status
+
+```python
+ | set_save_status(status: bool) -> None
+```
+
+Sets value of the save status
+
+<a name="models.newbasemodel.NewBaseModel.get_properties"></a>
+#### get\_properties
+
+```python
+ | @classmethod
+ | get_properties(cls, include: Union[Set, Dict, None], exclude: Union[Set, Dict, None]) -> Set[str]
+```
+
+Returns a set of names of functions/fields decorated with
+@property_field decorator.
+
+They are added to dictionary when called directly and therefore also are
+present in fastapi responses.
+
+**Arguments**:
+
+- `include (Union[Set, Dict, None])`: fields to include
+- `exclude (Union[Set, Dict, None])`: fields to exclude
+
+**Returns**:
+
+`(Set[str])`: set of property fields names
+
+<a name="models.newbasemodel.NewBaseModel._get_related_not_excluded_fields"></a>
+#### \_get\_related\_not\_excluded\_fields
+
+```python
+ | _get_related_not_excluded_fields(include: Optional[Dict], exclude: Optional[Dict]) -> List
+```
+
+Returns related field names applying on them include and exclude set.
+
+**Arguments**:
+
+- `include (Union[Set, Dict, None])`: fields to include
+- `exclude (Union[Set, Dict, None])`: fields to exclude
+
+**Returns**:
+
+`(List of fields with relations that is not excluded)`: 
+
+<a name="models.newbasemodel.NewBaseModel._extract_nested_models_from_list"></a>
+#### \_extract\_nested\_models\_from\_list
+
+```python
+ | @staticmethod
+ | _extract_nested_models_from_list(models: MutableSequence, include: Union[Set, Dict, None], exclude: Union[Set, Dict, None]) -> List
+```
+
+Converts list of models into list of dictionaries.
+
+**Arguments**:
+
+- `models (List)`: List of models
+- `include (Union[Set, Dict, None])`: fields to include
+- `exclude (Union[Set, Dict, None])`: fields to exclude
+
+**Returns**:
+
+`(List[Dict])`: list of models converted to dictionaries
+
+<a name="models.newbasemodel.NewBaseModel._skip_ellipsis"></a>
+#### \_skip\_ellipsis
+
+```python
+ | _skip_ellipsis(items: Union[Set, Dict, None], key: str) -> Union[Set, Dict, None]
+```
+
+Helper to traverse the include/exclude dictionaries.
+In dict() Ellipsis should be skipped as it indicates all fields required
+and not the actual set/dict with fields names.
+
+**Arguments**:
+
+- `items (Union[Set, Dict, None])`: current include/exclude value
+- `key (str)`: key for nested relations to check
+
+**Returns**:
+
+`(Union[Set, Dict, None])`: nested value of the items
+
+<a name="models.newbasemodel.NewBaseModel._extract_nested_models"></a>
+#### \_extract\_nested\_models
+
+```python
+ | _extract_nested_models(nested: bool, dict_instance: Dict, include: Optional[Dict], exclude: Optional[Dict]) -> Dict
+```
+
+Traverse nested models and converts them into dictionaries.
+Calls itself recursively if needed.
+
+**Arguments**:
+
+- `nested (bool)`: flag if current instance is nested
+- `dict_instance (Dict)`: current instance dict
+- `include (Optional[Dict])`: fields to include
+- `exclude (Optional[Dict])`: fields to exclude
+
+**Returns**:
+
+`(Dict)`: current model dict with child models converted to dictionaries
+
+<a name="models.newbasemodel.NewBaseModel.dict"></a>
+#### dict
+
+```python
+ | dict(*, include: Union[Set, Dict] = None, exclude: Union[Set, Dict] = None, by_alias: bool = False, skip_defaults: bool = None, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, nested: bool = False) -> "DictStrAny"
+```
+
+Generate a dictionary representation of the model,
+optionally specifying which fields to include or exclude.
+
+Nested models are also parsed to dictionaries.
+
+Additionally fields decorated with @property_field are also added.
+
+**Arguments**:
+
+- `include (Union[Set, Dict, None])`: fields to include
+- `exclude (Union[Set, Dict, None])`: fields to exclude
+- `by_alias (bool)`: flag to get values by alias - passed to pydantic
+- `skip_defaults (bool)`: flag to not set values - passed to pydantic
+- `exclude_unset (bool)`: flag to exclude not set values - passed to pydantic
+- `exclude_defaults (bool)`: flag to exclude default values - passed to pydantic
+- `exclude_none (bool)`: flag to exclude None values - passed to pydantic
+- `nested (bool)`: flag if the current model is nested
+
+**Returns**:
+
+`()`: 
+
+<a name="models.newbasemodel.NewBaseModel.update_from_dict"></a>
+#### update\_from\_dict
+
+```python
+ | update_from_dict(value_dict: Dict) -> "NewBaseModel"
+```
+
+Updates self with values of fields passed in the dictionary.
+
+**Arguments**:
+
+- `value_dict (Dict)`: dictionary of fields names and values
+
+**Returns**:
+
+`(NewBaseModel)`: self
+
+<a name="models.newbasemodel.NewBaseModel._convert_json"></a>
+#### \_convert\_json
+
+```python
+ | _convert_json(column_name: str, value: Any, op: str) -> Union[str, Dict]
+```
+
+Converts value to/from json if needed (for Json columns).
+
+**Arguments**:
+
+- `column_name (str)`: name of the field
+- `value (Any)`: value fo the field
+- `op (str)`: operator on json
+
+**Returns**:
+
+`(Any)`: converted value if needed, else original value
+
+<a name="models.newbasemodel.NewBaseModel._is_conversion_to_json_needed"></a>
+#### \_is\_conversion\_to\_json\_needed
+
+```python
+ | _is_conversion_to_json_needed(column_name: str) -> bool
+```
+
+Checks if given column name is related to JSON field.
+
+**Arguments**:
+
+- `column_name (str)`: name of the field
+
+**Returns**:
+
+`(bool)`: result of the check
+
+<a name="models.newbasemodel.NewBaseModel._extract_own_model_fields"></a>
+#### \_extract\_own\_model\_fields
+
+```python
+ | _extract_own_model_fields() -> Dict
+```
+
+Returns a dictionary with field names and values for fields that are not
+relations fields (ForeignKey, ManyToMany etc.)
+
+**Returns**:
+
+`(Dict)`: dictionary of fields names and values.
+
+<a name="models.newbasemodel.NewBaseModel._extract_model_db_fields"></a>
+#### \_extract\_model\_db\_fields
+
+```python
+ | _extract_model_db_fields() -> Dict
+```
+
+Returns a dictionary with field names and values for fields that are stored in
+current model's table.
+
+That includes own non-relational fields ang foreign key fields.
+
+**Returns**:
+
+`(Dict)`: dictionary of fields names and values.
+
+<a name="models.newbasemodel.NewBaseModel.get_relation_model_id"></a>
+#### get\_relation\_model\_id
+
+```python
+ | get_relation_model_id(target_field: Type["BaseField"]) -> Optional[int]
+```
+
+Returns an id of the relation side model to use in prefetch query.
+
+**Arguments**:
+
+- `target_field (Type["BaseField"])`: field with relation definition
+
+**Returns**:
+
+`(Optional[int])`: value of pk if set
+