next part of the docs and api documentation in beta ver

docs/api/models/helpers/relations.md

@@ -0,0 +1,154 @@
+<a name="models.helpers.relations"></a>
+# models.helpers.relations
+
+<a name="models.helpers.relations.alias_manager"></a>
+#### alias\_manager
+
+<a name="models.helpers.relations.register_relation_on_build"></a>
+#### register\_relation\_on\_build
+
+```python
+register_relation_on_build(new_model: Type["Model"], field_name: str) -> None
+```
+
+Registers ForeignKey relation in alias_manager to set a table_prefix.
+Registration include also reverse relation side to be able to join both sides.
+
+Relation is registered by model name and relation field name to allow for multiple
+relations between two Models that needs to have different
+aliases for proper sql joins.
+
+**Arguments**:
+
+- `new_model (Model class)`: constructed model
+- `field_name (str)`: name of the related field
+
+<a name="models.helpers.relations.register_many_to_many_relation_on_build"></a>
+#### register\_many\_to\_many\_relation\_on\_build
+
+```python
+register_many_to_many_relation_on_build(new_model: Type["Model"], field: Type[ManyToManyField], field_name: str) -> None
+```
+
+Registers connection between through model and both sides of the m2m relation.
+Registration include also reverse relation side to be able to join both sides.
+
+Relation is registered by model name and relation field name to allow for multiple
+relations between two Models that needs to have different
+aliases for proper sql joins.
+
+By default relation name is a model.name.lower().
+
+**Arguments**:
+
+- `field_name (str)`: name of the relation key
+- `new_model (Model class)`: model on which m2m field is declared
+- `field (ManyToManyField class)`: relation field
+
+<a name="models.helpers.relations.expand_reverse_relationships"></a>
+#### expand\_reverse\_relationships
+
+```python
+expand_reverse_relationships(model: Type["Model"]) -> None
+```
+
+Iterates through model_fields of given model and verifies if all reverse
+relation have been populated on related models.
+
+If the reverse relation has not been set before it's set here.
+
+**Arguments**:
+
+- `model (Model class)`: model on which relation should be checked and registered
+
+<a name="models.helpers.relations.register_reverse_model_fields"></a>
+#### register\_reverse\_model\_fields
+
+```python
+register_reverse_model_fields(model: Type["Model"], child: Type["Model"], related_name: str, model_field: Type["ForeignKeyField"]) -> None
+```
+
+Registers reverse ForeignKey field on related model.
+By default it's name.lower()+'s' of the model on which relation is defined.
+
+But if the related_model name is provided it's registered with that name.
+Autogenerated reverse fields also set related_name to the original field name.
+
+**Arguments**:
+
+- `model (Model class)`: related model on which reverse field should be defined
+- `child (Model class)`: parent model with relation definition
+- `related_name (str)`: name by which reverse key should be registered
+- `model_field (relation Field)`: original relation ForeignKey field
+
+<a name="models.helpers.relations.register_relation_in_alias_manager"></a>
+#### register\_relation\_in\_alias\_manager
+
+```python
+register_relation_in_alias_manager(new_model: Type["Model"], field: Type[ForeignKeyField], field_name: str) -> None
+```
+
+Registers the relation (and reverse relation) in alias manager.
+The m2m relations require registration of through model between
+actual end models of the relation.
+
+Delegates the actual registration to:
+m2m - register_many_to_many_relation_on_build
+fk - register_relation_on_build
+
+**Arguments**:
+
+- `new_model (Model class)`: model on which relation field is declared
+- `field (ForeignKey or ManyToManyField class)`: relation field
+- `field_name (str)`: name of the relation key
+
+<a name="models.helpers.relations.verify_related_name_dont_duplicate"></a>
+#### verify\_related\_name\_dont\_duplicate
+
+```python
+verify_related_name_dont_duplicate(child: Type["Model"], parent_model: Type["Model"], related_name: str) -> None
+```
+
+Verifies whether the used related_name (regardless of the fact if user defined or
+auto generated) is already used on related model, but is connected with other model
+than the one that we connect right now.
+
+**Raises**:
+
+- `ModelDefinitionError`: if name is already used but lead to different related
+model
+
+**Arguments**:
+
+- `child (ormar.models.metaclass.ModelMetaclass)`: related Model class
+- `parent_model (ormar.models.metaclass.ModelMetaclass)`: parent Model class
+- `related_name ()`: 
+
+**Returns**:
+
+`(None)`: None
+
+<a name="models.helpers.relations.reverse_field_not_already_registered"></a>
+#### reverse\_field\_not\_already\_registered
+
+```python
+reverse_field_not_already_registered(child: Type["Model"], child_model_name: str, parent_model: Type["Model"]) -> bool
+```
+
+Checks if child is already registered in parents pydantic fields.
+
+**Raises**:
+
+- `ModelDefinitionError`: if related name is already used but lead to different
+related model
+
+**Arguments**:
+
+- `child (ormar.models.metaclass.ModelMetaclass)`: related Model class
+- `child_model_name (str)`: related_name of the child if provided
+- `parent_model (ormar.models.metaclass.ModelMetaclass)`: parent Model class
+
+**Returns**:
+
+`(bool)`: result of the check
+