next part of the docs and api documentation in beta ver

ormar/models/__init__.py

@@ -1,3 +1,9 @@
+"""
+Definition of Model, it's parents NewBaseModel and mixins used by models.
+Also defines a Metaclass that handles all constructions and relations registration,
+ass well as vast number of helper functions for pydantic, sqlalchemy and relations.
+"""
+
 from ormar.models.newbasemodel import NewBaseModel  # noqa I100
 from ormar.models.model import Model  # noqa I100
 

ormar/models/helpers/models.py

@@ -61,7 +61,7 @@ def validate_related_names_in_relations(
     (populated by default as model.name.lower()+'s').
     Also related_names have to be unique for given related model.
 
-    :raises: ModelDefinitionError if validation of related_names fail
+    :raises ModelDefinitionError: if validation of related_names fail
     :param model_fields: dictionary of declared ormar model fields
     :type model_fields: Dict[str, ormar.Field]
     :param new_model:

ormar/models/helpers/relations.py

@@ -157,7 +157,7 @@ def verify_related_name_dont_duplicate(
     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
+    :raises ModelDefinitionError: if name is already used but lead to different related
     model
     :param child: related Model class
     :type child: ormar.models.metaclass.ModelMetaclass
@@ -191,7 +191,7 @@ def reverse_field_not_already_registered(
     """
     Checks if child is already registered in parents pydantic fields.
 
-    :raises: ModelDefinitionError if related name is already used but lead to different
+    :raises ModelDefinitionError: if related name is already used but lead to different
     related model
     :param child: related Model class
     :type child: ormar.models.metaclass.ModelMetaclass

ormar/models/helpers/sqlalchemy.py

@@ -84,7 +84,7 @@ def check_pk_column_validity(
     was not already set (only one allowed per model) and if field is not marked
     as pydantic_only as it needs to be a database field.
 
-    :raises: ModelDefintionError if pkname already set or field is pydantic_only
+    :raises ModelDefintionError: if pkname already set or field is pydantic_only
     :param field_name: name of field
     :type field_name: str
     :param field: ormar.Field
@@ -121,7 +121,7 @@ def sqlalchemy_columns_from_model_fields(
     Append fields to columns if it's not pydantic_only,
     virtual ForeignKey or ManyToMany field.
 
-    :raises: ModelDefinitionError if validation of related_names fail,
+    :raises ModelDefinitionError: if validation of related_names fail,
     or pkname validation fails.
     :param model_fields: dictionary of declared ormar model fields
     :type model_fields: Dict[str, ormar.Field]
@@ -162,7 +162,7 @@ def populate_meta_tablename_columns_and_pk(
     If not calls the sqlalchemy_columns_from_model_fields to populate
     columns from ormar.fields definitions.
 
-    :raises: if pkname is not present raises ModelDefinitionError.
+    :raises ModelDefinitionError: if pkname is not present raises ModelDefinitionError.
     Each model has to have pk.
 
     :param name: name of the current Model

ormar/models/metaclass.py

@@ -48,7 +48,7 @@ CONFIG_KEY = "Config"
 class ModelMeta:
     """
     Class used for type hinting.
-    Users can subclass this one for conveniance but it's not required.
+    Users can subclass this one for convenience but it's not required.
     The only requirement is that ormar.Model has to have inner class with name Meta.
     """
 
@@ -86,7 +86,7 @@ def choices_validator(cls: Type["Model"], values: Dict[str, Any]) -> Dict[str, A
     Validator that is attached to pydantic model pre root validators.
     Validator checks if field value is in field.choices list.
 
-    :raises: ValueError if field value is outside of allowed choices.
+    :raises ValueError: if field value is outside of allowed choices.
     :param cls: constructed class
     :type cls: Model class
     :param values: dictionary of field values (pydantic side)
@@ -321,7 +321,7 @@ def copy_data_from_parent_model(  # noqa: CCR001
     Since relation fields requires different related_name for different children
 
 
-    :raises: ModelDefinitionError if non abstract model is subclassed
+    :raises ModelDefinitionError: if non abstract model is subclassed
     :param base_class: one of the parent classes
     :type base_class: Model or model parent class
     :param curr_class: current constructed class
@@ -500,6 +500,7 @@ class ModelMetaclass(pydantic.main.ModelMetaclass):
         Construct parent pydantic Metaclass/ Model.
 
         If class has Meta class declared (so actual ormar Models) it also:
+
         * populate sqlalchemy columns, pkname and tables from model_fields
         * register reverse relationships on related models
         * registers all relations in alias manager that populates table_prefixes

ormar/models/mixins/save_mixin.py

@@ -12,7 +12,7 @@ class SavePrepareMixin(RelationMixin, AliasMixin):
     """
 
     @classmethod
-    def _prepare_model_to_save(cls, new_kwargs: dict) -> dict:
+    def prepare_model_to_save(cls, new_kwargs: dict) -> dict:
         """
         Combines all preparation methods before saving.
         Removes primary key for if it's nullable or autoincrement pk field,

ormar/models/model.py

@@ -456,7 +456,7 @@ class Model(NewBaseModel):
 
         Sets model save status to True.
 
-        :raises: If the pk column is not set will throw ModelPersistenceError
+        :raises ModelPersistenceError: If the pk column is not set
 
         :param kwargs: list of fields to update as field=value pairs
         :type kwargs: Any
@@ -512,7 +512,7 @@ class Model(NewBaseModel):
         Be careful as the related models can be overwritten by pk_only models in load.
         Does NOT refresh the related models fields if they were loaded before.
 
-        :raises: If given pk is not found in database the NoMatch exception is raised.
+        :raises NoMatch: If given pk is not found in database.
 
         :return: reloaded Model
         :rtype: Model

ormar/models/newbasemodel.py

@@ -103,7 +103,7 @@ class NewBaseModel(pydantic.BaseModel, ModelTableProxy, metaclass=ModelMetaclass
         should be explicitly set to None, as otherwise pydantic will try to populate
         them with their default values if default is set.
 
-        :raises: ModelError if abstract model is initialized or unknown field is passed
+        :raises ModelError: if abstract model is initialized or unknown field is passed
         :param args: ignored args
         :type args: Any
         :param kwargs: keyword arguments - all fields values and some special params