fix isnull typo and formatting

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

@@ -78,12 +78,12 @@ Primary key field is always added and cannot be excluded (will be added anyway).
 
 `(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
+<a name="models.mixins.excludable_mixin.ExcludableMixin._update_excluded_with_related"></a>
+#### \_update\_excluded\_with\_related
 
 ```python
  | @classmethod
- | _update_excluded_with_related_not_required(cls, exclude: Union["AbstractSetIntStr", "MappingIntStrAny", None], nested: bool = False) -> Union[Set, Dict]
+ | _update_excluded_with_related(cls, exclude: Union[Set, Dict, None]) -> Set
 ```
 
 Used during generation of the dict().
@@ -96,7 +96,6 @@ 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**:
 

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

@@ -19,7 +19,7 @@ in the end all parent (main) models should be unique.
 
 ```python
  | @classmethod
- | merge_instances_list(cls, result_rows: Sequence["Model"]) -> Sequence["Model"]
+ | merge_instances_list(cls, result_rows: List["Model"]) -> List["Model"]
 ```
 
 Merges a list of models into list of unique models.
@@ -41,7 +41,7 @@ populated, each instance is one row in db and some models can duplicate
 
 ```python
  | @classmethod
- | merge_two_instances(cls, one: "Model", other: "Model") -> "Model"
+ | merge_two_instances(cls, one: "Model", other: "Model", relation_map: Dict = None) -> "Model"
 ```
 
 Merges current (other) Model and previous one (one) and returns the current
@@ -51,6 +51,7 @@ 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
 
@@ -58,3 +59,30 @@ If needed it's calling itself recurrently and merges also children models.
 
 `(Model)`: current Model instance with data merged from previous one.
 
+<a name="models.mixins.merge_mixin.MergeModelMixin._merge_items_lists"></a>
+#### \_merge\_items\_lists
+
+```python
+ | @classmethod
+ | _merge_items_lists(cls, field_name: str, current_field: List, other_value: List, relation_map: Optional[Dict]) -> List
+```
+
+Takes two list of nested models and process them going deeper
+according with the map.
+
+If model from one's list is in other -> they are merged with relations
+to follow passed from map.
+
+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
+
+**Returns**:
+
+`(List[Model])`: merged list of models
+

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

@@ -59,7 +59,7 @@ or field name specified by related parameter.
 
 ```python
  | @classmethod
- | get_related_field_name(cls, target_field: Type["ForeignKeyField"]) -> str
+ | get_related_field_name(cls, target_field: "ForeignKeyField") -> str
 ```
 
 Returns name of the relation field that should be used in prefetch query.

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

@@ -30,7 +30,7 @@ related fields.
 
 ```python
  | @classmethod
- | extract_related_fields(cls) -> List
+ | extract_related_fields(cls) -> List["ForeignKeyField"]
 ```
 
 Returns List of ormar Fields for all relations declared on a model.
@@ -45,7 +45,7 @@ List is cached in cls._related_fields for quicker access.
 
 ```python
  | @classmethod
- | extract_through_names(cls) -> Set
+ | extract_through_names(cls) -> Set[str]
 ```
 
 Extracts related fields through names which are shortcuts to through models.
@@ -84,43 +84,35 @@ related fields that are not stored as foreign keys on given model.
 
 `(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 name="models.mixins.relation_mixin.RelationMixin._iterate_related_models"></a>
 #### \_iterate\_related\_models
 
 ```python
  | @classmethod
- | _iterate_related_models(cls, visited: Set[Union[Type["Model"], Type["RelationMixin"]]] = None, source_relation: str = None, source_model: Union[Type["Model"], Type["RelationMixin"]] = None) -> List[str]
+ | _iterate_related_models(cls, node_list: NodeList = None, source_relation: str = None) -> List[str]
 ```
 
 Iterates related models recursively to extract relation strings of
 nested not visited models.
 
+**Returns**:
+
+`(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
+
+```python
+ | @staticmethod
+ | _get_final_relations(processed_relations: List, source_relation: Optional[str]) -> List[str]
+```
+
+Helper method to prefix nested relation strings with current source relation
+
 **Arguments**:
 
-- `visited (Set[str])`: set of already visited models
+- `processed_relations (List[str])`: list of already processed relation str
 - `source_relation (str)`: name of the current relation
-- `source_model (Type["Model"])`: model from which relation comes in nested relations
 
 **Returns**:
 

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

@@ -33,6 +33,25 @@ Translate columns into aliases (db names).
 
 `(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
+
+```python
+ | @classmethod
+ | _remove_not_ormar_fields(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._remove_pk_from_kwargs"></a>
 #### \_remove\_pk\_from\_kwargs
 
@@ -52,6 +71,25 @@ and it's set to None.
 
 `(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
+
+```python
+ | @classmethod
+ | parse_non_db_fields(cls, model_dict: Dict) -> Dict
+```
+
+Receives dictionary of model that is about to be saved and changes uuid fields
+to strings in bulk_update.
+
+**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.substitute_models_with_pks"></a>
 #### substitute\_models\_with\_pks
 
@@ -110,3 +148,73 @@ fields with choices set to see if the value is allowed.
 
 `(Dict)`: dictionary of model that is about to be saved
 
+<a name="models.mixins.save_mixin.SavePrepareMixin._upsert_model"></a>
+#### \_upsert\_model
+
+```python
+ | @staticmethod
+ | async _upsert_model(instance: "Model", save_all: bool, previous_model: Optional["Model"], relation_field: Optional["ForeignKeyField"], update_count: int) -> int
+```
+
+Method updates given instance if:
+
+* instance is not saved or
+* instance have no pk or
+* save_all=True flag is set
+
+and instance is not __pk_only__.
+
+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
+
+**Returns**:
+
+`(int)`: no of updated models
+
+<a name="models.mixins.save_mixin.SavePrepareMixin._upsert_through_model"></a>
+#### \_upsert\_through\_model
+
+```python
+ | @staticmethod
+ | async _upsert_through_model(instance: "Model", previous_model: "Model", relation_field: "ForeignKeyField") -> None
+```
+
+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
+
+<a name="models.mixins.save_mixin.SavePrepareMixin._update_relation_list"></a>
+#### \_update\_relation\_list
+
+```python
+ | async _update_relation_list(fields_list: Collection["ForeignKeyField"], follow: bool, save_all: bool, relation_map: Dict, update_count: int) -> int
+```
+
+Internal method used in save_related to follow deeper from
+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
+
+**Returns**:
+
+`(int)`: tuple of update count and visited
+