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

16
docs/api/models/mixins/alias-mixin.md
View File

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

56
docs/api/models/mixins/excludable-mixin.md
View File

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

22
docs/api/models/mixins/merge-model-mixin.md
View File

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

28
docs/api/models/mixins/prefetch-query-mixin.md
View File

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

18
docs/api/models/mixins/relation-mixin.md
View File

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

74
docs/api/models/mixins/save-prepare-mixin.md
View File

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