add docs

docs/api/models/descriptors/descriptors.md

@@ -0,0 +1,62 @@
+<a name="models.descriptors.descriptors"></a>
+# models.descriptors.descriptors
+
+<a name="models.descriptors.descriptors.PydanticDescriptor"></a>
+## PydanticDescriptor Objects
+
+```python
+class PydanticDescriptor()
+```
+
+Pydantic descriptor simply delegates everything to pydantic model
+
+<a name="models.descriptors.descriptors.JsonDescriptor"></a>
+## JsonDescriptor Objects
+
+```python
+class JsonDescriptor()
+```
+
+Json descriptor dumps/loads strings to actual data on write/read
+
+<a name="models.descriptors.descriptors.BytesDescriptor"></a>
+## BytesDescriptor Objects
+
+```python
+class BytesDescriptor()
+```
+
+Bytes descriptor converts strings to bytes on write and converts bytes to str
+if represent_as_base64_str flag is set, so the value can be dumped to json
+
+<a name="models.descriptors.descriptors.PkDescriptor"></a>
+## PkDescriptor Objects
+
+```python
+class PkDescriptor()
+```
+
+As of now it's basically a copy of PydanticDescriptor but that will
+change in the future with multi column primary keys
+
+<a name="models.descriptors.descriptors.RelationDescriptor"></a>
+## RelationDescriptor Objects
+
+```python
+class RelationDescriptor()
+```
+
+Relation descriptor expands the relation to initialize the related model
+before setting it to __dict__. Note that expanding also registers the
+related model in RelationManager.
+
+<a name="models.descriptors.descriptors.PropertyDescriptor"></a>
+## PropertyDescriptor Objects
+
+```python
+class PropertyDescriptor()
+```
+
+Property descriptor handles methods decorated with @property_field decorator.
+They are read only.
+

docs/api/models/excludable-items.md

@@ -22,7 +22,7 @@ Return copy of self to avoid in place modifications
 
 **Returns**:
 
-`(ormar.models.excludable.Excludable)`: copy of self with copied sets
+`ormar.models.excludable.Excludable`: copy of self with copied sets
 
 <a name="models.excludable.Excludable.set_values"></a>
 #### set\_values
@@ -35,8 +35,8 @@ Appends the data to include/exclude sets.
 
 **Arguments**:
 
-- `value (set)`: set of values to add
-- `is_exclude (bool)`: flag if values are to be excluded or included
+- `value` (`set`): set of values to add
+- `is_exclude` (`bool`): flag if values are to be excluded or included
 
 <a name="models.excludable.Excludable.is_included"></a>
 #### is\_included
@@ -49,11 +49,11 @@ Check if field in included (in set or set is {...})
 
 **Arguments**:
 
-- `key (str)`: key to check
+- `key` (`str`): key to check
 
 **Returns**:
 
-`(bool)`: result of the check
+`bool`: result of the check
 
 <a name="models.excludable.Excludable.is_excluded"></a>
 #### is\_excluded
@@ -66,11 +66,11 @@ Check if field in excluded (in set or set is {...})
 
 **Arguments**:
 
-- `key (str)`: key to check
+- `key` (`str`): key to check
 
 **Returns**:
 
-`(bool)`: result of the check
+`bool`: result of the check
 
 <a name="models.excludable.ExcludableItems"></a>
 ## ExcludableItems Objects
@@ -95,11 +95,20 @@ Copy passed ExcludableItems to avoid inplace modifications.
 
 **Arguments**:
 
-- `other (ormar.models.excludable.ExcludableItems)`: other excludable items to be copied
+- `other` (`ormar.models.excludable.ExcludableItems`): other excludable items to be copied
 
 **Returns**:
 
-`(ormar.models.excludable.ExcludableItems)`: copy of other
+`ormar.models.excludable.ExcludableItems`: copy of other
+
+<a name="models.excludable.ExcludableItems.include_entry_count"></a>
+#### include\_entry\_count
+
+```python
+ | include_entry_count() -> int
+```
+
+Returns count of include items inside
 
 <a name="models.excludable.ExcludableItems.get"></a>
 #### get
@@ -112,12 +121,12 @@ Return Excludable for given model and alias.
 
 **Arguments**:
 
-- `model_cls (ormar.models.metaclass.ModelMetaclass)`: target model to check
-- `alias (str)`: table alias from relation manager
+- `model_cls` (`ormar.models.metaclass.ModelMetaclass`): target model to check
+- `alias` (`str`): table alias from relation manager
 
 **Returns**:
 
-`(ormar.models.excludable.Excludable)`: Excludable for given model and alias
+`ormar.models.excludable.Excludable`: Excludable for given model and alias
 
 <a name="models.excludable.ExcludableItems.build"></a>
 #### build
@@ -133,9 +142,9 @@ Each excludable has two sets of values - one to include, one to exclude.
 
 **Arguments**:
 
-- `items (Union[List[str], str, Tuple[str], Set[str], Dict])`: values to be included or excluded
-- `model_cls (ormar.models.metaclass.ModelMetaclass)`: source model from which relations are constructed
-- `is_exclude (bool)`: flag if items should be included or excluded
+- `items` (`Union[List[str], str, Tuple[str], Set[str], Dict]`): values to be included or excluded
+- `model_cls` (`ormar.models.metaclass.ModelMetaclass`): source model from which relations are constructed
+- `is_exclude` (`bool`): flag if items should be included or excluded
 
 <a name="models.excludable.ExcludableItems._set_excludes"></a>
 #### \_set\_excludes
@@ -148,10 +157,10 @@ Sets set of values to be included or excluded for given key and model.
 
 **Arguments**:
 
-- `items (set)`: items to include/exclude
-- `model_name (str)`: name of model to construct key
-- `is_exclude (bool)`: flag if values should be included or excluded
-- `alias (str)`: 
+- `items` (`set`): items to include/exclude
+- `model_name` (`str`): name of model to construct key
+- `is_exclude` (`bool`): flag if values should be included or excluded
+- `alias` (`str`): 
 
 <a name="models.excludable.ExcludableItems._traverse_dict"></a>
 #### \_traverse\_dict
@@ -164,12 +173,12 @@ Goes through dict of nested values and construct/update Excludables.
 
 **Arguments**:
 
-- `values (Dict)`: items to include/exclude
-- `source_model (ormar.models.metaclass.ModelMetaclass)`: source model from which relations are constructed
-- `model_cls (ormar.models.metaclass.ModelMetaclass)`: model from which current relation is constructed
-- `is_exclude (bool)`: flag if values should be included or excluded
-- `related_items (List)`: list of names of related fields chain
-- `alias (str)`: alias of relation
+- `values` (`Dict`): items to include/exclude
+- `source_model` (`ormar.models.metaclass.ModelMetaclass`): source model from which relations are constructed
+- `model_cls` (`ormar.models.metaclass.ModelMetaclass`): model from which current relation is constructed
+- `is_exclude` (`bool`): flag if values should be included or excluded
+- `related_items` (`List`): list of names of related fields chain
+- `alias` (`str`): alias of relation
 
 <a name="models.excludable.ExcludableItems._traverse_list"></a>
 #### \_traverse\_list
@@ -182,7 +191,7 @@ Goes through list of values and construct/update Excludables.
 
 **Arguments**:
 
-- `values (set)`: items to include/exclude
-- `model_cls (ormar.models.metaclass.ModelMetaclass)`: model from which current relation is constructed
-- `is_exclude (bool)`: flag if values should be included or excluded
+- `values` (`set`): items to include/exclude
+- `model_cls` (`ormar.models.metaclass.ModelMetaclass`): model from which current relation is constructed
+- `is_exclude` (`bool`): flag if values should be included or excluded
 

docs/api/models/helpers/models.md

@@ -13,11 +13,11 @@ are ForwardRefs that needs to be updated before proceeding.
 
 **Arguments**:
 
-- `field (Type[BaseField])`: model field to verify
+- `field` (`Type[BaseField]`): model field to verify
 
 **Returns**:
 
-`(bool)`: result of the check
+`bool`: result of the check
 
 <a name="models.helpers.models.populate_default_options_values"></a>
 #### populate\_default\_options\_values
@@ -37,8 +37,8 @@ Current options are:
 
 **Arguments**:
 
-- `new_model (Model class)`: newly constructed Model
-- `model_fields (Union[Dict[str, type], Dict])`: dict of model fields
+- `new_model` (`Model class`): newly constructed Model
+- `model_fields` (`Union[Dict[str, type], Dict]`): dict of model fields
 
 <a name="models.helpers.models.substitue_backend_pool_for_sqlite"></a>
 #### substitue\_backend\_pool\_for\_sqlite
@@ -52,7 +52,7 @@ executes "PRAGMA foreign_keys=1; on initialization to enable foreign keys.
 
 **Arguments**:
 
-- `new_model (Model class)`: newly declared ormar Model
+- `new_model` (`Model class`): newly declared ormar Model
 
 <a name="models.helpers.models.check_required_meta_parameters"></a>
 #### check\_required\_meta\_parameters
@@ -67,7 +67,7 @@ Recreates Connection pool for sqlite3
 
 **Arguments**:
 
-- `new_model (Model class)`: newly declared ormar Model
+- `new_model` (`Model class`): newly declared ormar Model
 
 <a name="models.helpers.models.extract_annotations_and_default_vals"></a>
 #### extract\_annotations\_and\_default\_vals
@@ -81,11 +81,11 @@ extraction of ormar model_fields.
 
 **Arguments**:
 
-- `attrs (Dict)`: namespace of the class created
+- `attrs` (`Dict`): namespace of the class created
 
 **Returns**:
 
-`(Tuple[Dict, Dict])`: namespace of the class updated, dict of extracted model_fields
+`Tuple[Dict, Dict]`: namespace of the class updated, dict of extracted model_fields
 
 <a name="models.helpers.models.group_related_list"></a>
 #### group\_related\_list
@@ -106,11 +106,11 @@ Result dictionary is sorted by length of the values and by key
 
 **Arguments**:
 
-- `list_ (List[str])`: list of related models used in select related
+- `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
+`Dict[str, List]`: list converted to dictionary to avoid repetition and group nested models
 
 <a name="models.helpers.models.meta_field_not_set"></a>
 #### meta\_field\_not\_set
@@ -125,10 +125,10 @@ Then check if it's set to something truthful
 
 **Arguments**:
 
-- `model (Model class)`: newly constructed model
-- `field_name (str)`: name of the ormar field
+- `model` (`Model class`): newly constructed model
+- `field_name` (`str`): name of the ormar field
 
 **Returns**:
 
-`(bool)`: result of the check
+`bool`: result of the check
 

docs/api/models/helpers/pydantic.md

@@ -15,9 +15,9 @@ 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
+- `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
@@ -31,12 +31,12 @@ 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
+- `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
+`pydantic.ModelField`: newly created pydantic field
 
 <a name="models.helpers.pydantic.populate_pydantic_default_values"></a>
 #### populate\_pydantic\_default\_values
@@ -58,11 +58,11 @@ Those annotations are later used by pydantic to construct it's own fields.
 
 **Arguments**:
 
-- `attrs (Dict)`: current class namespace
+- `attrs` (`Dict`): current class namespace
 
 **Returns**:
 
-`(Tuple[Dict, Dict])`: namespace of the class updated, dict of extracted model_fields
+`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
@@ -75,7 +75,7 @@ Returns empty pydantic Config with orm_mode set to True.
 
 **Returns**:
 
-`(pydantic Config)`: empty default config with orm_mode set.
+`pydantic Config`: empty default config with orm_mode set.
 
 <a name="models.helpers.pydantic.get_potential_fields"></a>
 #### get\_potential\_fields
@@ -88,9 +88,22 @@ Gets all the fields in current class namespace that are Fields.
 
 **Arguments**:
 
-- `attrs (Dict)`: current class namespace
+- `attrs` (`Dict`): current class namespace
 
 **Returns**:
 
-`(Dict)`: extracted fields that are ormar Fields
+`Dict`: extracted fields that are ormar Fields
+
+<a name="models.helpers.pydantic.remove_excluded_parent_fields"></a>
+#### remove\_excluded\_parent\_fields
+
+```python
+remove_excluded_parent_fields(model: Type["Model"]) -> None
+```
+
+Removes pydantic fields that should be excluded from parent models
+
+**Arguments**:
+
+- `model` (`Type["Model"]`): 
 

docs/api/models/helpers/related-names-validation.md

@@ -20,6 +20,6 @@ Also related_names have to be unique for given related model.
 
 **Arguments**:
 
-- `model_fields (Dict[str, ormar.Field])`: dictionary of declared ormar model fields
-- `new_model (Model class)`: 
+- `model_fields` (`Dict[str, ormar.Field]`): dictionary of declared ormar model fields
+- `new_model` (`Model class`): 
 

docs/api/models/helpers/relations.md

@@ -17,7 +17,7 @@ aliases for proper sql joins.
 
 **Arguments**:
 
-- `field (ForeignKey class)`: relation field
+- `field` (`ForeignKey class`): relation field
 
 <a name="models.helpers.relations.register_many_to_many_relation_on_build"></a>
 #### register\_many\_to\_many\_relation\_on\_build
@@ -37,7 +37,7 @@ By default relation name is a model.name.lower().
 
 **Arguments**:
 
-- `field (ManyToManyField class)`: relation field
+- `field` (`ManyToManyField class`): relation field
 
 <a name="models.helpers.relations.expand_reverse_relationship"></a>
 #### expand\_reverse\_relationship
@@ -50,11 +50,11 @@ If the reverse relation has not been set before it's set here.
 
 **Arguments**:
 
-- `model_field ()`: 
+- `model_field`: 
 
 **Returns**:
 
-`(None)`: None
+`None`: None
 
 <a name="models.helpers.relations.expand_reverse_relationships"></a>
 #### expand\_reverse\_relationships
@@ -70,7 +70,7 @@ 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
+- `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
@@ -87,7 +87,7 @@ Autogenerated reverse fields also set related_name to the original field name.
 
 **Arguments**:
 
-- `model_field (relation Field)`: original relation ForeignKey field
+- `model_field` (`relation Field`): original relation ForeignKey field
 
 <a name="models.helpers.relations.register_through_shortcut_fields"></a>
 #### register\_through\_shortcut\_fields
@@ -100,7 +100,7 @@ Registers m2m relation through shortcut on both ends of the relation.
 
 **Arguments**:
 
-- `model_field (ManyToManyField)`: relation field defined in parent model
+- `model_field` (`ManyToManyField`): relation field defined in parent model
 
 <a name="models.helpers.relations.register_relation_in_alias_manager"></a>
 #### register\_relation\_in\_alias\_manager
@@ -119,7 +119,7 @@ fk - register_relation_on_build
 
 **Arguments**:
 
-- `field (ForeignKey or ManyToManyField class)`: relation field
+- `field` (`ForeignKey or ManyToManyField class`): relation field
 
 <a name="models.helpers.relations.verify_related_name_dont_duplicate"></a>
 #### verify\_related\_name\_dont\_duplicate
@@ -139,12 +139,12 @@ model
 
 **Arguments**:
 
-- `related_name ()`: 
-- `model_field (relation Field)`: original relation ForeignKey field
+- `related_name`: 
+- `model_field` (`relation Field`): original relation ForeignKey field
 
 **Returns**:
 
-`(None)`: None
+`None`: None
 
 <a name="models.helpers.relations.reverse_field_not_already_registered"></a>
 #### reverse\_field\_not\_already\_registered
@@ -162,9 +162,9 @@ related model
 
 **Arguments**:
 
-- `model_field (relation Field)`: original relation ForeignKey field
+- `model_field` (`relation Field`): original relation ForeignKey field
 
 **Returns**:
 
-`(bool)`: result of the check
+`bool`: result of the check
 

docs/api/models/helpers/sqlalchemy.md

@@ -15,7 +15,7 @@ Sets pydantic fields with child and parent model types.
 
 **Arguments**:
 
-- `model_field (ManyToManyField)`: relation field defined in parent model
+- `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
@@ -30,9 +30,9 @@ Newly created field is added to m2m relation through model Meta columns and tabl
 
 **Arguments**:
 
-- `field_name (str)`: name of the column to create
-- `model (Model class)`: Model class to which FK should be created
-- `model_field (ManyToManyField field)`: field with ManyToMany relation
+- `field_name` (`str`): name of the column to create
+- `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
@@ -51,13 +51,13 @@ as pydantic_only as it needs to be a database field.
 
 **Arguments**:
 
-- `field_name (str)`: name of field
-- `field (BaseField)`: ormar.Field
-- `pkname (Optional[str])`: already set pkname
+- `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
+`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
@@ -91,12 +91,12 @@ or pkname validation fails.
 
 **Arguments**:
 
-- `model_fields (Dict[str, ormar.Field])`: dictionary of declared ormar model fields
-- `new_model (Model class)`: 
+- `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
+`Tuple[Optional[str], List[sqlalchemy.Column]]`: pkname, list of sqlalchemy columns
 
 <a name="models.helpers.sqlalchemy._process_fields"></a>
 #### \_process\_fields
@@ -123,12 +123,12 @@ or pkname validation fails.
 
 **Arguments**:
 
-- `model_fields (Dict[str, ormar.Field])`: dictionary of declared ormar model fields
-- `new_model (Model class)`: 
+- `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
+`Tuple[Optional[str], List[sqlalchemy.Column]]`: pkname, list of sqlalchemy columns
 
 <a name="models.helpers.sqlalchemy._is_through_model_not_set"></a>
 #### \_is\_through\_model\_not\_set
@@ -141,11 +141,11 @@ Alias to if check that verifies if through model was created.
 
 **Arguments**:
 
-- `field ("BaseField")`: field to check
+- `field` (`"BaseField"`): field to check
 
 **Returns**:
 
-`(bool)`: result of the check
+`bool`: result of the check
 
 <a name="models.helpers.sqlalchemy._is_db_field"></a>
 #### \_is\_db\_field
@@ -158,11 +158,11 @@ Alias to if check that verifies if field should be included in database.
 
 **Arguments**:
 
-- `field ("BaseField")`: field to check
+- `field` (`"BaseField"`): field to check
 
 **Returns**:
 
-`(bool)`: result of the check
+`bool`: result of the check
 
 <a name="models.helpers.sqlalchemy.populate_meta_tablename_columns_and_pk"></a>
 #### populate\_meta\_tablename\_columns\_and\_pk
@@ -185,12 +185,12 @@ Each model has to have pk.
 
 **Arguments**:
 
-- `name (str)`: name of the current Model
-- `new_model (ormar.models.metaclass.ModelMetaclass)`: currently constructed Model
+- `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
+`ormar.models.metaclass.ModelMetaclass`: Model with populated pkname and columns in Meta
 
 <a name="models.helpers.sqlalchemy.check_for_null_type_columns_from_forward_refs"></a>
 #### check\_for\_null\_type\_columns\_from\_forward\_refs
@@ -203,11 +203,11 @@ Check is any column is of NUllType() meaning it's empty column from ForwardRef
 
 **Arguments**:
 
-- `meta (Model class Meta)`: Meta class of the Model without sqlalchemy table constructed
+- `meta` (`Model class Meta`): Meta class of the Model without sqlalchemy table constructed
 
 **Returns**:
 
-`(bool)`: result of the check
+`bool`: result of the check
 
 <a name="models.helpers.sqlalchemy.populate_meta_sqlalchemy_table_if_required"></a>
 #### populate\_meta\_sqlalchemy\_table\_if\_required
@@ -221,11 +221,11 @@ It populates name, metadata, columns and constraints.
 
 **Arguments**:
 
-- `meta (Model class Meta)`: Meta class of the Model without sqlalchemy table constructed
+- `meta` (`Model class Meta`): Meta class of the Model without sqlalchemy table constructed
 
 **Returns**:
 
-`(Model class)`: class with populated Meta.table
+`Model class`: class with populated Meta.table
 
 <a name="models.helpers.sqlalchemy.update_column_definition"></a>
 #### update\_column\_definition
@@ -238,10 +238,10 @@ Updates a column with a new type column based on updated parameters in FK fields
 
 **Arguments**:
 
-- `model (Type["Model"])`: model on which columns needs to be updated
-- `field (ForeignKeyField)`: field with column definition that requires update
+- `model` (`Type["Model"]`): model on which columns needs to be updated
+- `field` (`ForeignKeyField`): field with column definition that requires update
 
 **Returns**:
 
-`(None)`: None
+`None`: None
 

docs/api/models/helpers/validation.md

@@ -13,11 +13,11 @@ A if it has one, a validator for this field needs to be attached.
 
 **Arguments**:
 
-- `field (BaseField)`: ormar field to check
+- `field` (`BaseField`): ormar field to check
 
 **Returns**:
 
-`(bool)`: result of the check
+`bool`: result of the check
 
 <a name="models.helpers.validation.convert_choices_if_needed"></a>
 #### convert\_choices\_if\_needed
@@ -37,12 +37,12 @@ Converts decimal to float with given scale.
 
 **Arguments**:
 
-- `field (BaseField)`: ormar field to check with choices
-- `values (Dict)`: current values of the model to verify
+- `field` (`BaseField`): ormar field to check with choices
+- `values` (`Dict`): current values of the model to verify
 
 **Returns**:
 
-`(Tuple[Any, List])`: value, choices list
+`Tuple[Any, List]`: value, choices list
 
 <a name="models.helpers.validation.validate_choices"></a>
 #### validate\_choices
@@ -59,8 +59,8 @@ Validates if given value is in provided choices.
 
 **Arguments**:
 
-- `field (BaseField)`: field to validate
-- `value (Any)`: value of the field
+- `field` (`BaseField`): field to validate
+- `value` (`Any`): value of the field
 
 <a name="models.helpers.validation.choices_validator"></a>
 #### choices\_validator
@@ -78,12 +78,130 @@ Validator checks if field value is in field.choices list.
 
 **Arguments**:
 
-- `cls (Model class)`: constructed class
-- `values (Dict[str, Any])`: dictionary of field values (pydantic side)
+- `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
+`Dict[str, Any]`: values if pass validation, otherwise exception is raised
+
+<a name="models.helpers.validation.generate_model_example"></a>
+#### generate\_model\_example
+
+```python
+generate_model_example(model: Type["Model"], relation_map: Dict = None) -> Dict
+```
+
+Generates example to be included in schema in fastapi.
+
+**Arguments**:
+
+- `model` (`Type["Model"]`): ormar.Model
+- `relation_map` (`Optional[Dict]`): dict with relations to follow
+
+**Returns**:
+
+`Dict[str, int]`: dict with example values
+
+<a name="models.helpers.validation.populates_sample_fields_values"></a>
+#### populates\_sample\_fields\_values
+
+```python
+populates_sample_fields_values(example: Dict[str, Any], name: str, field: BaseField, relation_map: Dict = None) -> None
+```
+
+Iterates the field and sets fields to sample values
+
+**Arguments**:
+
+- `field` (`BaseField`): ormar field
+- `name` (`str`): name of the field
+- `example` (`Dict[str, Any]`): example dict
+- `relation_map` (`Optional[Dict]`): dict with relations to follow
+
+<a name="models.helpers.validation.get_nested_model_example"></a>
+#### get\_nested\_model\_example
+
+```python
+get_nested_model_example(name: str, field: "BaseField", relation_map: Dict) -> Union[List, Dict]
+```
+
+Gets representation of nested model.
+
+**Arguments**:
+
+- `name` (`str`): name of the field to follow
+- `field` (`BaseField`): ormar field
+- `relation_map` (`Dict`): dict with relation map
+
+**Returns**:
+
+`Union[List, Dict]`: nested model or list of nested model repr
+
+<a name="models.helpers.validation.generate_pydantic_example"></a>
+#### generate\_pydantic\_example
+
+```python
+generate_pydantic_example(pydantic_model: Type[pydantic.BaseModel], exclude: Set = None) -> Dict
+```
+
+Generates dict with example.
+
+**Arguments**:
+
+- `pydantic_model` (`Type[pydantic.BaseModel]`): model to parse
+- `exclude` (`Optional[Set]`): list of fields to exclude
+
+**Returns**:
+
+`Dict`: dict with fields and sample values
+
+<a name="models.helpers.validation.get_pydantic_example_repr"></a>
+#### get\_pydantic\_example\_repr
+
+```python
+get_pydantic_example_repr(type_: Any) -> Any
+```
+
+Gets sample representation of pydantic field for example dict.
+
+**Arguments**:
+
+- `type_` (`Any`): type of pydantic field
+
+**Returns**:
+
+`Any`: representation to include in example
+
+<a name="models.helpers.validation.overwrite_example_and_description"></a>
+#### overwrite\_example\_and\_description
+
+```python
+overwrite_example_and_description(schema: Dict[str, Any], model: Type["Model"]) -> None
+```
+
+Overwrites the example with properly nested children models.
+Overwrites the description if it's taken from ormar.Model.
+
+**Arguments**:
+
+- `schema` (`Dict[str, Any]`): schema of current model
+- `model` (`Type["Model"]`): model class
+
+<a name="models.helpers.validation.overwrite_binary_format"></a>
+#### overwrite\_binary\_format
+
+```python
+overwrite_binary_format(schema: Dict[str, Any], model: Type["Model"]) -> None
+```
+
+Overwrites format of the field if it's a LargeBinary field with
+a flag to represent the field as base64 encoded string.
+
+**Arguments**:
+
+- `schema` (`Dict[str, Any]`): schema of current model
+- `model` (`Type["Model"]`): model class
 
 <a name="models.helpers.validation.construct_modify_schema_function"></a>
 #### construct\_modify\_schema\_function
@@ -96,13 +214,32 @@ Modifies the schema to include fields with choices validator.
 Those fields will be displayed in schema as Enum types with available choices
 values listed next to them.
 
+Note that schema extra has to be a function, otherwise it's called to soon
+before all the relations are expanded.
+
 **Arguments**:
 
-- `fields_with_choices (List)`: list of fields with choices validation
+- `fields_with_choices` (`List`): list of fields with choices validation
 
 **Returns**:
 
-`(Callable)`: callable that will be run by pydantic to modify the schema
+`Callable`: callable that will be run by pydantic to modify the schema
+
+<a name="models.helpers.validation.construct_schema_function_without_choices"></a>
+#### construct\_schema\_function\_without\_choices
+
+```python
+construct_schema_function_without_choices() -> SchemaExtraCallable
+```
+
+Modifies model example and description if needed.
+
+Note that schema extra has to be a function, otherwise it's called to soon
+before all the relations are expanded.
+
+**Returns**:
+
+`Callable`: callable that will be run by pydantic to modify the schema
 
 <a name="models.helpers.validation.populate_choices_validators"></a>
 #### populate\_choices\_validators
@@ -116,5 +253,5 @@ If yes it adds choices validation into pre root validators.
 
 **Arguments**:
 
-- `model (Model class)`: newly constructed Model
+- `model` (`Model class`): newly constructed Model
 

docs/api/models/mixins/alias-mixin.md

@@ -23,11 +23,11 @@ For fields without alias field name is returned.
 
 **Arguments**:
 
-- `field_name (str)`: name of the field to get alias from
+- `field_name` (`str`): name of the field to get alias from
 
 **Returns**:
 
-`(str)`: alias (db name) if set, otherwise passed name
+`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
@@ -42,11 +42,11 @@ If field do not have alias it's returned as is.
 
 **Arguments**:
 
-- `alias (str)`: 
+- `alias` (`str`): 
 
 **Returns**:
 
-`(str)`: field name if set, otherwise passed alias (db name)
+`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
@@ -62,11 +62,11 @@ Only fields present in the dictionary are translated.
 
 **Arguments**:
 
-- `new_kwargs (Dict)`: dict with fields names and their values
+- `new_kwargs` (`Dict`): dict with fields names and their values
 
 **Returns**:
 
-`(Dict)`: dict with aliases and their values
+`Dict`: dict with aliases and their values
 
 <a name="models.mixins.alias_mixin.AliasMixin.translate_aliases_to_columns"></a>
 #### translate\_aliases\_to\_columns
@@ -82,9 +82,9 @@ Only fields present in the dictionary are translated.
 
 **Arguments**:
 
-- `new_kwargs (Dict)`: dict with aliases and their values
+- `new_kwargs` (`Dict`): dict with aliases and their values
 
 **Returns**:
 
-`(Dict)`: dict with fields names and their values
+`Dict`: dict with fields names and their values
 

docs/api/models/mixins/excludable-mixin.md

@@ -23,12 +23,12 @@ passed items.
 
 **Arguments**:
 
-- `items (Union[Set, Dict, None])`: bag of items to include or exclude
-- `key (str)`: name of the child to extract
+- `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
+`Union[Set, Dict, None]`: child extracted from items if exists
 
 <a name="models.mixins.excludable_mixin.ExcludableMixin._populate_pk_column"></a>
 #### \_populate\_pk\_column
@@ -43,20 +43,20 @@ 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
+- `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
+`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: Union[Type["Model"], Type["ModelRow"]], excludable: ExcludableItems, alias: str = "", use_alias: bool = False) -> List[str]
+ | own_table_columns(cls, model: Union[Type["Model"], Type["ModelRow"]], excludable: ExcludableItems, alias: str = "", use_alias: bool = False, add_pk_columns: bool = True) -> List[str]
 ```
 
 Returns list of aliases or field names for given model.
@@ -69,14 +69,15 @@ Primary key field is always added and cannot be excluded (will be added anyway).
 
 **Arguments**:
 
-- `alias (str)`: relation prefix
-- `excludable (ExcludableItems)`: structure of fields to include and exclude
-- `model (Type["Model"])`: model on columns are selected
-- `use_alias (bool)`: flag if aliases or field names should be used
+- `add_pk_columns` (`bool`): flag if add primary key - always yes if ormar parses data
+- `alias` (`str`): relation prefix
+- `excludable` (`ExcludableItems`): structure of fields to include and exclude
+- `model` (`Type["Model"]`): model on columns are selected
+- `use_alias` (`bool`): flag if aliases or field names should be used
 
 **Returns**:
 
-`(List[str])`: list of column field names or aliases
+`List[str]`: list of column field names or aliases
 
 <a name="models.mixins.excludable_mixin.ExcludableMixin._update_excluded_with_related"></a>
 #### \_update\_excluded\_with\_related
@@ -95,11 +96,30 @@ exclusion, for nested models all related models are excluded.
 
 **Arguments**:
 
-- `exclude (Union[Set, Dict, None])`: set/dict with fields to exclude
+- `exclude` (`Union[Set, Dict, None]`): set/dict with fields to exclude
 
 **Returns**:
 
-`(Union[Set, Dict])`: set or dict with excluded fields added.
+`Union[Set, Dict]`: set or dict with excluded fields added.
+
+<a name="models.mixins.excludable_mixin.ExcludableMixin._update_excluded_with_pks_and_through"></a>
+#### \_update\_excluded\_with\_pks\_and\_through
+
+```python
+ | @classmethod
+ | _update_excluded_with_pks_and_through(cls, exclude: Set, exclude_primary_keys: bool, exclude_through_models: bool) -> Set
+```
+
+Updates excluded names with name of pk column if exclude flag is set.
+
+**Arguments**:
+
+- `exclude` (`Set`): set of names to exclude
+- `exclude_primary_keys` (`bool`): flag if the primary keys should be excluded
+
+**Returns**:
+
+`Set`: set updated with pk if flag is set
 
 <a name="models.mixins.excludable_mixin.ExcludableMixin.get_names_to_exclude"></a>
 #### get\_names\_to\_exclude
@@ -120,10 +140,10 @@ them with dicts constructed from those db rows.
 
 **Arguments**:
 
-- `alias (str)`: alias of current relation
-- `excludable (ExcludableItems)`: structure of fields to include and exclude
+- `alias` (`str`): alias of current relation
+- `excludable` (`ExcludableItems`): structure of fields to include and exclude
 
 **Returns**:
 
-`(Set)`: set of field names that should be excluded
+`Set`: set of field names that should be excluded
 

docs/api/models/mixins/merge-model-mixin.md

@@ -29,12 +29,12 @@ 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
+- `result_rows` (`List["Model"]`): list of already initialized Models with child models
 
 **Returns**:
 
-`(List["Model"])`: list of merged models where each main model is unique
+`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
@@ -51,13 +51,13 @@ If needed it's calling itself recurrently and merges also children models.
 
 **Arguments**:
 
-- `relation_map (Dict)`: map of models relations to follow
-- `one (Model)`: previous model instance
-- `other (Model)`: current model instance
+- `relation_map` (`Dict`): map of models relations to follow
+- `one` (`Model`): previous model instance
+- `other` (`Model`): current model instance
 
 **Returns**:
 
-`(Model)`: current Model instance with data merged from previous one.
+`Model`: current Model instance with data merged from previous one.
 
 <a name="models.mixins.merge_mixin.MergeModelMixin._merge_items_lists"></a>
 #### \_merge\_items\_lists
@@ -77,12 +77,12 @@ If one's model is not in other it's simply appended to the list.
 
 **Arguments**:
 
-- `field_name (str)`: name of the current relation field
-- `current_field (List[Model])`: list of nested models from one model
-- `other_value (List[Model])`: list of nested models from other model
-- `relation_map (Dict)`: map of relations to follow
+- `field_name` (`str`): name of the current relation field
+- `current_field` (`List[Model]`): list of nested models from one model
+- `other_value` (`List[Model]`): list of nested models from other model
+- `relation_map` (`Dict`): map of relations to follow
 
 **Returns**:
 
-`(List[Model])`: merged list of models
+`List[Model]`: merged list of models
 

docs/api/models/mixins/prefetch-query-mixin.md

@@ -22,14 +22,14 @@ 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
+- `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
+`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
@@ -45,14 +45,14 @@ 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
+- `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
@@ -68,11 +68,11 @@ populate relations dict, and populate nested model in prefetch query.
 
 **Arguments**:
 
-- `target_field (Type[BaseField])`: relation field that should be used in prefetch
+- `target_field` (`Type[BaseField]`): relation field that should be used in prefetch
 
 **Returns**:
 
-`(str)`: name of the field
+`str`: name of the field
 
 <a name="models.mixins.prefetch_mixin.PrefetchQueryMixin.get_filtered_names_to_extract"></a>
 #### get\_filtered\_names\_to\_extract
@@ -92,9 +92,9 @@ Only relations from current model are returned.
 
 **Arguments**:
 
-- `prefetch_dict (Dict)`: dictionary of fields to extract
+- `prefetch_dict` (`Dict`): dictionary of fields to extract
 
 **Returns**:
 
-`(List)`: list of fields names to extract
+`List`: list of fields names to extract
 

docs/api/models/mixins/relation-mixin.md

@@ -23,7 +23,7 @@ related fields.
 
 **Returns**:
 
-`(Set)`: set of model fields with relation fields excluded
+`Set`: set of model fields with relation fields excluded
 
 <a name="models.mixins.relation_mixin.RelationMixin.extract_related_fields"></a>
 #### extract\_related\_fields
@@ -38,7 +38,7 @@ List is cached in cls._related_fields for quicker access.
 
 **Returns**:
 
-`(List)`: list of related fields
+`List`: list of related fields
 
 <a name="models.mixins.relation_mixin.RelationMixin.extract_through_names"></a>
 #### extract\_through\_names
@@ -52,7 +52,7 @@ Extracts related fields through names which are shortcuts to through models.
 
 **Returns**:
 
-`(Set)`: set of related through fields names
+`Set`: set of related through fields names
 
 <a name="models.mixins.relation_mixin.RelationMixin.extract_related_names"></a>
 #### extract\_related\_names
@@ -67,7 +67,7 @@ List is cached in cls._related_names for quicker access.
 
 **Returns**:
 
-`(Set)`: set of related fields names
+`Set`: set of related fields names
 
 <a name="models.mixins.relation_mixin.RelationMixin._extract_db_related_names"></a>
 #### \_extract\_db\_related\_names
@@ -82,7 +82,7 @@ related fields that are not stored as foreign keys on given model.
 
 **Returns**:
 
-`(Set)`: set of model fields with non fk relation fields excluded
+`Set`: set of model fields with non fk relation fields excluded
 
 <a name="models.mixins.relation_mixin.RelationMixin._iterate_related_models"></a>
 #### \_iterate\_related\_models
@@ -97,7 +97,7 @@ nested not visited models.
 
 **Returns**:
 
-`(List[str])`: list of relation strings to be passed to select_related
+`List[str]`: list of relation strings to be passed to select_related
 
 <a name="models.mixins.relation_mixin.RelationMixin._get_final_relations"></a>
 #### \_get\_final\_relations
@@ -111,10 +111,10 @@ Helper method to prefix nested relation strings with current source relation
 
 **Arguments**:
 
-- `processed_relations (List[str])`: list of already processed relation str
-- `source_relation (str)`: name of the current relation
+- `processed_relations` (`List[str]`): list of already processed relation str
+- `source_relation` (`str`): name of the current relation
 
 **Returns**:
 
-`(List[str])`: list of relation strings to be passed to select_related
+`List[str]`: list of relation strings to be passed to select_related
 

docs/api/models/mixins/save-prepare-mixin.md

@@ -27,11 +27,11 @@ Translate columns into aliases (db names).
 
 **Arguments**:
 
-- `new_kwargs (Dict[str, str])`: dictionary of model that is about to be saved
+- `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
+`Dict[str, str]`: dictionary of model that is about to be saved
 
 <a name="models.mixins.save_mixin.SavePrepareMixin._remove_not_ormar_fields"></a>
 #### \_remove\_not\_ormar\_fields
@@ -46,11 +46,11 @@ and it's set to None.
 
 **Arguments**:
 
-- `new_kwargs (Dict[str, str])`: dictionary of model that is about to be saved
+- `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
+`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
@@ -65,11 +65,11 @@ and it's set to None.
 
 **Arguments**:
 
-- `new_kwargs (Dict[str, str])`: dictionary of model that is about to be saved
+- `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
+`Dict[str, str]`: dictionary of model that is about to be saved
 
 <a name="models.mixins.save_mixin.SavePrepareMixin.parse_non_db_fields"></a>
 #### parse\_non\_db\_fields
@@ -84,11 +84,11 @@ to strings in bulk_update.
 
 **Arguments**:
 
-- `model_dict (Dict)`: dictionary of model that is about to be saved
+- `model_dict` (`Dict`): dictionary of model that is about to be saved
 
 **Returns**:
 
-`(Dict)`: dictionary of model that is about to be saved
+`Dict`: 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
@@ -103,11 +103,11 @@ models that are stored as foreign keys to their fk value.
 
 **Arguments**:
 
-- `model_dict (Dict)`: dictionary of model that is about to be saved
+- `model_dict` (`Dict`): dictionary of model that is about to be saved
 
 **Returns**:
 
-`(Dict)`: dictionary of model that is about to be saved
+`Dict`: dictionary of model that is about to be saved
 
 <a name="models.mixins.save_mixin.SavePrepareMixin.populate_default_values"></a>
 #### populate\_default\_values
@@ -123,11 +123,11 @@ passed by the user.
 
 **Arguments**:
 
-- `new_kwargs (Dict)`: dictionary of model that is about to be saved
+- `new_kwargs` (`Dict`): dictionary of model that is about to be saved
 
 **Returns**:
 
-`(Dict)`: dictionary of model that is about to be saved
+`Dict`: dictionary of model that is about to be saved
 
 <a name="models.mixins.save_mixin.SavePrepareMixin.validate_choices"></a>
 #### validate\_choices
@@ -142,11 +142,11 @@ fields with choices set to see if the value is allowed.
 
 **Arguments**:
 
-- `new_kwargs (Dict)`: dictionary of model that is about to be saved
+- `new_kwargs` (`Dict`): dictionary of model that is about to be saved
 
 **Returns**:
 
-`(Dict)`: dictionary of model that is about to be saved
+`Dict`: dictionary of model that is about to be saved
 
 <a name="models.mixins.save_mixin.SavePrepareMixin._upsert_model"></a>
 #### \_upsert\_model
@@ -168,15 +168,15 @@ If relation leading to instance is a ManyToMany also the through model is saved
 
 **Arguments**:
 
-- `instance (Model)`: current model to upsert
-- `save_all (bool)`: flag if all models should be saved or only not saved ones
-- `relation_field (Optional[ForeignKeyField])`: field with relation
-- `previous_model (Model)`: previous model from which method came
-- `update_count (int)`: no of updated models
+- `instance` (`Model`): current model to upsert
+- `save_all` (`bool`): flag if all models should be saved or only not saved ones
+- `relation_field` (`Optional[ForeignKeyField]`): field with relation
+- `previous_model` (`Model`): previous model from which method came
+- `update_count` (`int`): no of updated models
 
 **Returns**:
 
-`(int)`: no of updated models
+`int`: no of updated models
 
 <a name="models.mixins.save_mixin.SavePrepareMixin._upsert_through_model"></a>
 #### \_upsert\_through\_model
@@ -190,9 +190,9 @@ Upsert through model for m2m relation.
 
 **Arguments**:
 
-- `instance (Model)`: current model to upsert
-- `relation_field (Optional[ForeignKeyField])`: field with relation
-- `previous_model (Model)`: previous model from which method came
+- `instance` (`Model`): current model to upsert
+- `relation_field` (`Optional[ForeignKeyField]`): field with relation
+- `previous_model` (`Model`): previous model from which method came
 
 <a name="models.mixins.save_mixin.SavePrepareMixin._update_relation_list"></a>
 #### \_update\_relation\_list
@@ -206,15 +206,33 @@ related models and update numbers of updated related instances.
 
 **Arguments**:
 
-- `fields_list (Collection["ForeignKeyField"])`: list of ormar fields to follow and save
-- `relation_map (Dict)`: map of relations 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
-- `update_count (int)`: internal parameter for recursive calls -
 number of updated instances
+- `save_all` (`bool`): 
+- `fields_list` (`Collection["ForeignKeyField"]`): list of ormar fields to follow and save
+- `relation_map` (`Dict`): map of relations to follow
+- `follow` (`bool`): flag to trigger deep save -
+- `update_count` (`int`): internal parameter for recursive calls -
 
 **Returns**:
 
-`(int)`: tuple of update count and visited
+`int`: tuple of update count and visited
+
+<a name="models.mixins.save_mixin.SavePrepareMixin._get_field_values"></a>
+#### \_get\_field\_values
+
+```python
+ | _get_field_values(name: str) -> List
+```
+
+Extract field values and ensures it is a list.
+
+**Arguments**:
+
+- `name` (`str`): name of the field
+
+**Returns**:
+
+`List`: list of values
 

docs/api/models/model-metaclass.md

@@ -30,7 +30,7 @@ All properties here are used as "cache" to not recalculate them constantly.
 
 **Arguments**:
 
-- `new_model (Model class)`: newly constructed Model
+- `new_model` (`Model class`): newly constructed Model
 
 <a name="models.metaclass.add_property_fields"></a>
 #### add\_property\_fields
@@ -47,8 +47,8 @@ Names of property fields are cached for quicker access / extraction.
 
 **Arguments**:
 
-- `new_model (Model class)`: newly constructed model
-- `attrs (Dict[str, str])`: 
+- `new_model` (`Model class`): newly constructed model
+- `attrs` (`Dict[str, str]`): 
 
 <a name="models.metaclass.register_signals"></a>
 #### register\_signals
@@ -64,7 +64,7 @@ Signals are emitted in both model own methods and in selected queryset ones.
 
 **Arguments**:
 
-- `new_model (Model class)`: newly constructed model
+- `new_model` (`Model class`): newly constructed model
 
 <a name="models.metaclass.verify_constraint_names"></a>
 #### verify\_constraint\_names
@@ -79,9 +79,9 @@ 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
+- `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
@@ -94,9 +94,9 @@ 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
+- `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_and_replace_m2m_through_model"></a>
 #### copy\_and\_replace\_m2m\_through\_model
@@ -118,13 +118,13 @@ Removes the original sqlalchemy table from metadata if it was not removed.
 
 **Arguments**:
 
-- `base_class (Type["Model"])`: base class model
-- `field (ManyToManyField)`: field with relations definition
-- `field_name (str)`: name of the relation field
-- `table_name (str)`: name of the table
-- `parent_fields (Dict)`: dictionary of fields to copy to new models from parent
-- `attrs (Dict)`: new namespace for class being constructed
-- `meta (ModelMeta)`: metaclass of currently created model
+- `base_class` (`Type["Model"]`): base class model
+- `field` (`ManyToManyField`): field with relations definition
+- `field_name` (`str`): name of the relation field
+- `table_name` (`str`): name of the table
+- `parent_fields` (`Dict`): dictionary of fields to copy to new models from parent
+- `attrs` (`Dict`): new namespace for class being constructed
+- `meta` (`ModelMeta`): metaclass of currently created model
 
 <a name="models.metaclass.copy_data_from_parent_model"></a>
 #### copy\_data\_from\_parent\_model
@@ -133,7 +133,7 @@ Removes the original sqlalchemy table from metadata if it was not removed.
 copy_data_from_parent_model(base_class: Type["Model"], curr_class: type, attrs: Dict, model_fields: Dict[str, Union[BaseField, ForeignKeyField, ManyToManyField]]) -> Tuple[Dict, Dict]
 ```
 
-Copy the key parameters [databse, metadata, property_fields and constraints]
+Copy the key parameters [database, metadata, property_fields and constraints]
 and fields from parent models. Overwrites them if needed.
 
 Only abstract classes can be subclassed.
@@ -147,14 +147,14 @@ Since relation fields requires different related_name for different children
 
 **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
+- `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
+`Tuple[Dict, Dict]`: updated attrs and model_fields
 
 <a name="models.metaclass.extract_from_parents_definition"></a>
 #### extract\_from\_parents\_definition
@@ -163,7 +163,7 @@ Since relation fields requires different related_name for different children
 extract_from_parents_definition(base_class: type, curr_class: type, attrs: Dict, model_fields: Dict[str, Union[BaseField, ForeignKeyField, ManyToManyField]]) -> Tuple[Dict, Dict]
 ```
 
-Extracts fields from base classes if they have valid oramr fields.
+Extracts fields from base classes if they have valid ormar 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
@@ -176,14 +176,14 @@ 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
+- `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
+`Tuple[Dict, Dict]`: updated attrs and model_fields
 
 <a name="models.metaclass.update_attrs_and_fields"></a>
 #### update\_attrs\_and\_fields
@@ -197,11 +197,28 @@ as well as model.Meta.model_fields definitions from parents.
 
 **Arguments**:
 
-- `attrs (Dict)`: new namespace for class being constructed
-- `new_attrs (Dict)`: related 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
+- `attrs` (`Dict`): new namespace for class being constructed
+- `new_attrs` (`Dict`): related 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.add_field_descriptor"></a>
+#### add\_field\_descriptor
+
+```python
+add_field_descriptor(name: str, field: "BaseField", new_model: Type["Model"]) -> None
+```
+
+Sets appropriate descriptor for each model field.
+There are 5 main types of descriptors, for bytes, json, pure pydantic fields,
+and 2 ormar ones - one for relation and one for pk shortcut
+
+**Arguments**:
+
+- `name` (`str`): name of the field
+- `field` (`BaseField`): model field to add descriptor for
+- `new_model` (`Type["Model]`): model with fields
 
 <a name="models.metaclass.ModelMetaclass"></a>
 ## ModelMetaclass Objects
@@ -241,7 +258,25 @@ If class has Meta class declared (so actual ormar Models) it also:
 
 **Arguments**:
 
-- `name (str)`: name of current class
-- `bases (Tuple)`: base classes
-- `attrs (Dict)`: class namespace
+- `name` (`str`): name of current class
+- `bases` (`Tuple`): base classes
+- `attrs` (`Dict`): class namespace
+
+<a name="models.metaclass.ModelMetaclass.__getattr__"></a>
+#### \_\_getattr\_\_
+
+```python
+ | __getattr__(item: str) -> Any
+```
+
+Returns FieldAccessors on access to model fields from a class,
+that way it can be used in python style filters and order_by.
+
+**Arguments**:
+
+- `item` (`str`): name of the field
+
+**Returns**:
+
+`FieldAccessor`: FieldAccessor for given field
 

docs/api/models/model-row.md

@@ -30,19 +30,19 @@ nested models in result.
 
 **Arguments**:
 
-- `used_prefixes (List[str])`: list of already extracted prefixes
-- `proxy_source_model (Optional[Type["ModelRow"]])`: source model from which querysetproxy is constructed
-- `excludable (ExcludableItems)`: structure of fields to include and exclude
-- `current_relation_str (str)`: name of the relation field
-- `source_model (Type[Model])`: model on which relation was defined
-- `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
-- `related_field (ForeignKeyField)`: field with relation declaration
+- `used_prefixes` (`List[str]`): list of already extracted prefixes
+- `proxy_source_model` (`Optional[Type["ModelRow"]]`): source model from which querysetproxy is constructed
+- `excludable` (`ExcludableItems`): structure of fields to include and exclude
+- `current_relation_str` (`str`): name of the relation field
+- `source_model` (`Type[Model]`): model on which relation was defined
+- `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
+- `related_field` (`ForeignKeyField`): field with relation declaration
 
 **Returns**:
 
-`(Optional[Model])`: returns model if model is populated from database
+`Optional[Model]`: returns model if model is populated from database
 
 <a name="models.model_row.ModelRow._process_table_prefix"></a>
 #### \_process\_table\_prefix
@@ -54,14 +54,14 @@ nested models in result.
 
 **Arguments**:
 
-- `source_model (Type[Model])`: model on which relation was defined
-- `current_relation_str (str)`: current relation string
-- `related_field ("ForeignKeyField")`: field with relation declaration
-- `used_prefixes (List[str])`: list of already extracted prefixes
+- `source_model` (`Type[Model]`): model on which relation was defined
+- `current_relation_str` (`str`): current relation string
+- `related_field` (`"ForeignKeyField"`): field with relation declaration
+- `used_prefixes` (`List[str]`): list of already extracted prefixes
 
 **Returns**:
 
-`(str)`: table_prefix to use
+`str`: table_prefix to use
 
 <a name="models.model_row.ModelRow._populate_nested_models_from_row"></a>
 #### \_populate\_nested\_models\_from\_row
@@ -82,18 +82,17 @@ instances. In the end those instances are added to the final model dictionary.
 
 **Arguments**:
 
-- `proxy_source_model (Optional[Type["ModelRow"]])`: source model from which querysetproxy is constructed
-- `excludable (ExcludableItems)`: structure of fields to include and exclude
-- `source_model (Type[Model])`: source model from which relation started
-- `current_relation_str (str)`: joined related parts into one string
-- `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
+- `proxy_source_model` (`Optional[Type["ModelRow"]]`): source model from which querysetproxy is constructed
+- `excludable` (`ExcludableItems`): structure of fields to include and exclude
+- `source_model` (`Type[Model]`): source model from which relation started
+- `current_relation_str` (`str`): joined related parts into one string
+- `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
 
 **Returns**:
 
-`(Dict)`: dictionary with keys corresponding to model fields names
-and values are database values
+`Dict`: dictionary with keys corresponding to model fields names
 
 <a name="models.model_row.ModelRow._process_remainder_and_relation_string"></a>
 #### \_process\_remainder\_and\_relation\_string
@@ -107,9 +106,9 @@ Process remainder models and relation string
 
 **Arguments**:
 
-- `related_models (Union[Dict, List])`: list or dict of related models
-- `current_relation_str (Optional[str])`: current relation string
-- `related (str)`: name of the relation
+- `related_models` (`Union[Dict, List]`): list or dict of related models
+- `current_relation_str` (`Optional[str]`): current relation string
+- `related` (`str`): name of the relation
 
 <a name="models.model_row.ModelRow._populate_through_instance"></a>
 #### \_populate\_through\_instance
@@ -124,12 +123,12 @@ Normally it's child class, unless the query is from queryset.
 
 **Arguments**:
 
-- `row (sqlalchemy.engine.ResultProxy)`: row from db result
-- `item (Dict)`: parent item dict
-- `related (str)`: current relation name
-- `excludable (ExcludableItems)`: structure of fields to include and exclude
-- `child ("Model")`: child item of parent
-- `proxy_source_model (Type["Model"])`: source model from which querysetproxy is constructed
+- `row` (`sqlalchemy.engine.ResultProxy`): row from db result
+- `item` (`Dict`): parent item dict
+- `related` (`str`): current relation name
+- `excludable` (`ExcludableItems`): structure of fields to include and exclude
+- `child` (`"Model"`): child item of parent
+- `proxy_source_model` (`Type["Model"]`): source model from which querysetproxy is constructed
 
 <a name="models.model_row.ModelRow._create_through_instance"></a>
 #### \_create\_through\_instance
@@ -144,14 +143,14 @@ Excluded all relation fields and other exclude/include set in excludable.
 
 **Arguments**:
 
-- `row (sqlalchemy.engine.ResultProxy)`: loaded row from database
-- `through_name (str)`: name of the through field
-- `related (str)`: name of the relation
-- `excludable (ExcludableItems)`: structure of fields to include and exclude
+- `row` (`sqlalchemy.engine.ResultProxy`): loaded row from database
+- `through_name` (`str`): name of the through field
+- `related` (`str`): name of the relation
+- `excludable` (`ExcludableItems`): structure of fields to include and exclude
 
 **Returns**:
 
-`("ModelRow")`: initialized through model without relation
+`"ModelRow"`: initialized through model without relation
 
 <a name="models.model_row.ModelRow.extract_prefixed_table_columns"></a>
 #### extract\_prefixed\_table\_columns
@@ -174,15 +173,14 @@ Used in Model.from_row and PrefetchQuery._populate_rows methods.
 
 **Arguments**:
 
-- `excludable (ExcludableItems)`: structure of fields to include and exclude
-- `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.
+- `excludable` (`ExcludableItems`): structure of fields to include and exclude
+- `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
 
 **Returns**:
 
-`(Dict)`: dictionary with keys corresponding to model fields names
-and values are database values
+`Dict`: dictionary with keys corresponding to model fields names
 

docs/api/models/model-table-proxy.md

@@ -6,7 +6,11 @@
 
 ```python
 class ModelTableProxy(
-    PrefetchQueryMixin,  MergeModelMixin,  SavePrepareMixin,  ExcludableMixin)
+    PrefetchQueryMixin, 
+    MergeModelMixin, 
+    SavePrepareMixin, 
+    ExcludableMixin, 
+    PydanticMixin)
 ```
 
 Used to combine all mixins with different set of functionalities.

docs/api/models/model.md

@@ -21,11 +21,11 @@ For save kwargs are ignored, used only in update if provided.
 
 **Arguments**:
 
-- `kwargs (Any)`: list of fields to update
+- `kwargs` (`Any`): list of fields to update
 
 **Returns**:
 
-`(Model)`: saved Model
+`Model`: saved Model
 
 <a name="models.model.Model.save"></a>
 #### save
@@ -54,7 +54,7 @@ Sets model save status to True.
 
 **Returns**:
 
-`(Model)`: saved Model
+`Model`: saved Model
 
 <a name="models.model.Model.save_related"></a>
 #### save\_related
@@ -79,20 +79,20 @@ Nested relations of those kind need to be persisted manually.
 
 **Arguments**:
 
-- `relation_field (Optional[ForeignKeyField])`: field with relation leading to this model
-- `previous_model (Model)`: previous model from which method came
-- `exclude (Union[Set, Dict])`: items to exclude during saving of relations
-- `relation_map (Dict)`: map of relations to follow
-- `save_all (bool)`: flag if all models should be saved or only not saved ones
-- `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
-- `update_count (int)`: internal parameter for recursive calls -
 number of updated instances
+- `relation_field` (`Optional[ForeignKeyField]`): field with relation leading to this model
+- `previous_model` (`Model`): previous model from which method came
+- `exclude` (`Union[Set, Dict]`): items to exclude during saving of relations
+- `relation_map` (`Dict`): map of relations to follow
+- `save_all` (`bool`): flag if all models should be saved or only not saved ones
+- `follow` (`bool`): flag to trigger deep save -
+- `update_count` (`int`): internal parameter for recursive calls -
 
 **Returns**:
 
-`(int)`: number of updated/saved models
+`int`: number of updated/saved models
 
 <a name="models.model.Model.update"></a>
 #### update
@@ -110,8 +110,8 @@ Sets model save status to True.
 
 **Arguments**:
 
-- `_columns (List)`: list of columns to update, if None all are updated
-- `kwargs (Any)`: list of fields to update as field=value pairs
+- `_columns` (`List`): list of columns to update, if None all are updated
+- `kwargs` (`Any`): list of fields to update as field=value pairs
 
 **Raises**:
 
@@ -119,7 +119,7 @@ Sets model save status to True.
 
 **Returns**:
 
-`(Model)`: updated Model
+`Model`: updated Model
 
 <a name="models.model.Model.delete"></a>
 #### delete
@@ -140,7 +140,7 @@ or update and the Model will be saved in database again.
 
 **Returns**:
 
-`(int)`: number of deleted rows (for some backends)
+`int`: number of deleted rows (for some backends)
 
 <a name="models.model.Model.load"></a>
 #### load
@@ -159,7 +159,7 @@ Does NOT refresh the related models fields if they were loaded before.
 
 **Returns**:
 
-`(Model)`: reloaded Model
+`Model`: reloaded Model
 
 <a name="models.model.Model.load_all"></a>
 #### load\_all
@@ -185,11 +185,11 @@ Nested relations of those kind need to be loaded manually.
 
 **Arguments**:
 
-- `order_by (Union[List, str])`: columns by which models should be sorted
-- `exclude (Union[List, str, Set, Dict])`: related models to exclude
-- `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
+- `order_by` (`Union[List, str]`): columns by which models should be sorted
+- `exclude` (`Union[List, str, Set, Dict]`): related models to exclude
+- `follow` (`bool`): flag to trigger deep save -
 
 **Raises**:
 
@@ -197,5 +197,5 @@ with follow=True also related models of related models are saved
 
 **Returns**:
 
-`(Model)`: reloaded Model
+`Model`: reloaded Model
 

docs/api/models/new-basemodel.md

@@ -53,8 +53,8 @@ that has not been updated or unknown field is passed
 
 **Arguments**:
 
-- `args (Any)`: ignored args
-- `kwargs (Any)`: keyword arguments - all fields values and some special params
+- `args` (`Any`): ignored args
+- `kwargs` (`Any`): keyword arguments - all fields values and some special params
 
 <a name="models.newbasemodel.NewBaseModel.__setattr__"></a>
 #### \_\_setattr\_\_
@@ -63,71 +63,49 @@ that has not been updated or unknown field is passed
  | __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.
+Overwrites setattr in pydantic parent as otherwise descriptors are not called.
 
 **Arguments**:
 
-- `name (str)`: name of the attribute to set
-- `value (Any)`: value of the attribute to set
+- `name` (`str`): name of the attribute to set
+- `value` (`Any`): value of the attribute to set
 
 **Returns**:
 
-`(None)`: None
+`None`: None
 
-<a name="models.newbasemodel.NewBaseModel.__getattribute__"></a>
-#### \_\_getattribute\_\_
+<a name="models.newbasemodel.NewBaseModel.__getattr__"></a>
+#### \_\_getattr\_\_
 
 ```python
- | __getattribute__(item: str) -> Any
+ | __getattr__(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.
+Used only to silence mypy errors for Through models and reverse relations.
+Not used in real life as in practice calls are intercepted
+by RelationDescriptors
 
 **Arguments**:
 
-- `item (str)`: name of the attribute to retrieve
+- `item` (`str`): name of attribute
 
 **Returns**:
 
-`(Any)`: value of the attribute
+`Any`: Any
+
+<a name="models.newbasemodel.NewBaseModel._internal_set"></a>
+#### \_internal\_set
+
+```python
+ | _internal_set(name: str, value: Any) -> None
+```
+
+Delegates call to pydantic.
+
+**Arguments**:
+
+- `name` (`str`): name of param
+- `value` (`Any`): value to set
 
 <a name="models.newbasemodel.NewBaseModel._verify_model_can_be_initialized"></a>
 #### \_verify\_model\_can\_be\_initialized
@@ -140,24 +118,45 @@ Raises exception if model is abstract or has ForwardRefs in relation fields.
 
 **Returns**:
 
-`(None)`: None
+`None`: None
 
-<a name="models.newbasemodel.NewBaseModel._extract_related_model_instead_of_field"></a>
-#### \_extract\_related\_model\_instead\_of\_field
+<a name="models.newbasemodel.NewBaseModel._process_kwargs"></a>
+#### \_process\_kwargs
 
 ```python
- | _extract_related_model_instead_of_field(item: str) -> Optional[Union["Model", Sequence["Model"]]]
+ | _process_kwargs(kwargs: Dict) -> Tuple[Dict, Dict]
 ```
 
-Retrieves the related model/models from RelationshipManager.
+Initializes nested models.
+
+Removes property_fields
+
+Checks if field is in the model fields or pydatnic fields.
+
+Nullifies fields that should be excluded.
+
+Extracts through models from kwargs into temporary dict.
 
 **Arguments**:
 
-- `item (str)`: name of the relation
+- `kwargs` (`Dict`): passed to init keyword arguments
 
 **Returns**:
 
-`(Optional[Union[Model, List[Model]]])`: related model, list of related models or None
+`Tuple[Dict, Dict]`: modified kwargs
+
+<a name="models.newbasemodel.NewBaseModel._initialize_internal_attributes"></a>
+#### \_initialize\_internal\_attributes
+
+```python
+ | _initialize_internal_attributes() -> None
+```
+
+Initializes internal attributes during __init__()
+
+**Returns**:
+
+`None`: 
 
 <a name="models.newbasemodel.NewBaseModel.__eq__"></a>
 #### \_\_eq\_\_
@@ -170,11 +169,11 @@ Compares other model to this model. when == is called.
 
 **Arguments**:
 
-- `other (object)`: other model to compare
+- `other` (`object`): other model to compare
 
 **Returns**:
 
-`(bool)`: result of comparison
+`bool`: result of comparison
 
 <a name="models.newbasemodel.NewBaseModel.__same__"></a>
 #### \_\_same\_\_
@@ -191,11 +190,11 @@ Compares:
 
 **Arguments**:
 
-- `other (NewBaseModel)`: model to compare to
+- `other` (`NewBaseModel`): model to compare to
 
 **Returns**:
 
-`(bool)`: result of comparison
+`bool`: result of comparison
 
 <a name="models.newbasemodel.NewBaseModel.get_name"></a>
 #### get\_name
@@ -209,11 +208,11 @@ Returns name of the Model class, by default lowercase.
 
 **Arguments**:
 
-- `lower (bool)`: flag if name should be set to lowercase
+- `lower` (`bool`): flag if name should be set to lowercase
 
 **Returns**:
 
-`(str)`: name of the model
+`str`: name of the model
 
 <a name="models.newbasemodel.NewBaseModel.pk_column"></a>
 #### pk\_column
@@ -229,7 +228,7 @@ Only one primary key column is allowed.
 
 **Returns**:
 
-`(sqlalchemy.Column)`: primary key sqlalchemy column
+`sqlalchemy.Column`: primary key sqlalchemy column
 
 <a name="models.newbasemodel.NewBaseModel.saved"></a>
 #### saved
@@ -306,12 +305,12 @@ present in fastapi responses.
 
 **Arguments**:
 
-- `include (Union[Set, Dict, None])`: fields to include
-- `exclude (Union[Set, Dict, None])`: fields to exclude
+- `include` (`Union[Set, Dict, None]`): fields to include
+- `exclude` (`Union[Set, Dict, None]`): fields to exclude
 
 **Returns**:
 
-`(Set[str])`: set of property fields names
+`Set[str]`: set of property fields names
 
 <a name="models.newbasemodel.NewBaseModel.update_forward_refs"></a>
 #### update\_forward\_refs
@@ -335,55 +334,57 @@ Calls the pydantic method to evaluate pydantic fields.
 
 **Arguments**:
 
-- `localns (Any)`: local namespace
+- `localns` (`Any`): local namespace
 
 **Returns**:
 
-`(None)`: None
+`None`: None
 
 <a name="models.newbasemodel.NewBaseModel._get_not_excluded_fields"></a>
-#### \_get\_related\_not\_excluded\_fields
+#### \_get\_not\_excluded\_fields
 
 ```python
- | _get_not_excluded_fields(include: Optional[Dict], exclude: Optional[Dict]) -> List
+ | @staticmethod
+ | _get_not_excluded_fields(fields: Union[List, Set], 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
+- `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)`: 
+`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(relation_map: Dict, models: MutableSequence, include: Union[Set, Dict, None], exclude: Union[Set, Dict, None]) -> List
+ | _extract_nested_models_from_list(relation_map: Dict, models: MutableSequence, include: Union[Set, Dict, None], exclude: Union[Set, Dict, None], exclude_primary_keys: bool, exclude_through_models: bool) -> 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
+- `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
+`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, default_return: Any = None) -> Union[Set, Dict, None]
+ | @classmethod
+ | _skip_ellipsis(cls, items: Union[Set, Dict, None], key: str, default_return: Any = None) -> Union[Set, Dict, None]
 ```
 
 Helper to traverse the include/exclude dictionaries.
@@ -392,17 +393,18 @@ 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
+- `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
+`Union[Set, Dict, None]`: nested value of the items
 
 <a name="models.newbasemodel.NewBaseModel._convert_all"></a>
 #### \_convert\_all
 
 ```python
+ | @staticmethod
  | _convert_all(items: Union[Set, Dict, None]) -> Union[Set, Dict, None]
 ```
 
@@ -411,13 +413,13 @@ support index based exclusions.
 
 **Arguments**:
 
-- `items (Union[Set, Dict, None])`: current include/exclude value
+- `items` (`Union[Set, Dict, None]`): current include/exclude value
 
 <a name="models.newbasemodel.NewBaseModel._extract_nested_models"></a>
 #### \_extract\_nested\_models
 
 ```python
- | _extract_nested_models(relation_map: Dict, dict_instance: Dict, include: Optional[Dict], exclude: Optional[Dict]) -> Dict
+ | _extract_nested_models(relation_map: Dict, dict_instance: Dict, include: Optional[Dict], exclude: Optional[Dict], exclude_primary_keys: bool, exclude_through_models: bool) -> Dict
 ```
 
 Traverse nested models and converts them into dictionaries.
@@ -425,20 +427,20 @@ 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
+- `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
+`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, relation_map: Dict = None) -> "DictStrAny"
+ | 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, exclude_primary_keys: bool = False, exclude_through_models: bool = False, relation_map: Dict = None) -> "DictStrAny"
 ```
 
 Generate a dictionary representation of the model,
@@ -450,18 +452,33 @@ 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
-- `relation_map (Dict)`: map of the relations to follow to avoid circural deps
+- `exclude_through_models` (`bool`): flag to exclude through models from dict
+- `exclude_primary_keys` (`bool`): flag to exclude primary keys from dict
+- `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
+- `relation_map` (`Dict`): map of the relations to follow to avoid circural deps
 
 **Returns**:
 
-`()`: 
+
+
+<a name="models.newbasemodel.NewBaseModel.json"></a>
+#### json
+
+```python
+ | json(*, 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, encoder: Optional[Callable[[Any], Any]] = None, exclude_primary_keys: bool = False, exclude_through_models: bool = False, **dumps_kwargs: Any, ,) -> str
+```
+
+Generate a JSON representation of the model, `include` and `exclude`
+arguments as per `dict()`.
+
+`encoder` is an optional function to supply as `default` to json.dumps(),
+other arguments as per `json.dumps()`.
 
 <a name="models.newbasemodel.NewBaseModel.update_from_dict"></a>
 #### update\_from\_dict
@@ -474,47 +491,65 @@ Updates self with values of fields passed in the dictionary.
 
 **Arguments**:
 
-- `value_dict (Dict)`: dictionary of fields names and values
+- `value_dict` (`Dict`): dictionary of fields names and values
 
 **Returns**:
 
-`(NewBaseModel)`: self
+`NewBaseModel`: self
+
+<a name="models.newbasemodel.NewBaseModel._convert_to_bytes"></a>
+#### \_convert\_to\_bytes
+
+```python
+ | _convert_to_bytes(column_name: str, value: Any) -> Union[str, Dict]
+```
+
+Converts value to bytes from string
+
+**Arguments**:
+
+- `column_name` (`str`): name of the field
+- `value` (`Any`): value fo the field
+
+**Returns**:
+
+`Any`: converted value if needed, else original value
+
+<a name="models.newbasemodel.NewBaseModel._convert_bytes_to_str"></a>
+#### \_convert\_bytes\_to\_str
+
+```python
+ | _convert_bytes_to_str(column_name: str, value: Any) -> Union[str, Dict]
+```
+
+Converts value to str from bytes for represent_as_base64_str columns.
+
+**Arguments**:
+
+- `column_name` (`str`): name of the field
+- `value` (`Any`): value fo the field
+
+**Returns**:
+
+`Any`: converted value if needed, else original value
 
 <a name="models.newbasemodel.NewBaseModel._convert_json"></a>
 #### \_convert\_json
 
 ```python
- | _convert_json(column_name: str, value: Any, op: str) -> Union[str, Dict]
+ | _convert_json(column_name: str, value: Any) -> 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
+- `column_name` (`str`): name of the field
+- `value` (`Any`): value fo the field
 
 **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
+`Any`: converted value if needed, else original value
 
 <a name="models.newbasemodel.NewBaseModel._extract_own_model_fields"></a>
 #### \_extract\_own\_model\_fields
@@ -528,7 +563,7 @@ relations fields (ForeignKey, ManyToMany etc.)
 
 **Returns**:
 
-`(Dict)`: dictionary of fields names and values.
+`Dict`: dictionary of fields names and values.
 
 <a name="models.newbasemodel.NewBaseModel._extract_model_db_fields"></a>
 #### \_extract\_model\_db\_fields
@@ -544,7 +579,7 @@ That includes own non-relational fields ang foreign key fields.
 
 **Returns**:
 
-`(Dict)`: dictionary of fields names and values.
+`Dict`: dictionary of fields names and values.
 
 <a name="models.newbasemodel.NewBaseModel.get_relation_model_id"></a>
 #### get\_relation\_model\_id
@@ -557,9 +592,9 @@ Returns an id of the relation side model to use in prefetch query.
 
 **Arguments**:
 
-- `target_field ("BaseField")`: field with relation definition
+- `target_field` (`"BaseField"`): field with relation definition
 
 **Returns**:
 
-`(Optional[int])`: value of pk if set
+`Optional[int]`: value of pk if set
 

docs/api/models/traversible.md

@@ -21,13 +21,13 @@ Adds new Node or returns the existing one
 
 **Arguments**:
 
-- `node_class (ormar.models.metaclass.ModelMetaclass)`: Model in current node
-- `relation_name (str)`: name of the current relation
-- `parent_node (Optional[Node])`: parent node
+- `node_class` (`ormar.models.metaclass.ModelMetaclass`): Model in current node
+- `relation_name` (`str`): name of the current relation
+- `parent_node` (`Optional[Node]`): parent node
 
 **Returns**:
 
-`(Node)`: returns new or already existing node
+`Node`: returns new or already existing node
 
 <a name="models.traversible.NodeList.find"></a>
 #### find
@@ -40,13 +40,13 @@ Searches for existing node with given parameters
 
 **Arguments**:
 
-- `node_class (ormar.models.metaclass.ModelMetaclass)`: Model in current node
-- `relation_name (str)`: name of the current relation
-- `parent_node (Optional[Node])`: parent node
+- `node_class` (`ormar.models.metaclass.ModelMetaclass`): Model in current node
+- `relation_name` (`str`): name of the current relation
+- `parent_node` (`Optional[Node]`): parent node
 
 **Returns**:
 
-`(Optional[Node])`: returns already existing node or None
+`Optional[Node]`: returns already existing node or None
 
 <a name="models.traversible.Node"></a>
 ## Node Objects
@@ -70,9 +70,9 @@ Relation was visited if one of the parent node had the same Model class
 
 **Arguments**:
 
-- `relation_name (str)`: name of relation
+- `relation_name` (`str`): name of relation
 
 **Returns**:
 
-`(bool)`: result of the check
+`bool`: result of the check