Prodream/ormar
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

add docs

Browse Source
This commit is contained in:
collerek
2021-06-08 14:34:02 +02:00
parent a1557273b0
commit 96c9615229
49 changed files with 1917 additions and 994 deletions
Download Patch File Download Diff File Expand all files Collapse all files

26
docs/api/models/helpers/models.md
View File

@ -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

35
docs/api/models/helpers/pydantic.md
View File

@ -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"]`):

4
docs/api/models/helpers/related-names-validation.md
View File

@ -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`):

26
docs/api/models/helpers/relations.md
View File

@ -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

56
docs/api/models/helpers/sqlalchemy.md
View File

@ -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

163
docs/api/models/helpers/validation.md
View File

@ -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