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

next part of the docs and api documentation in beta ver

Browse Source
This commit is contained in:
collerek
2021-01-04 19:38:21 +01:00
parent eec17e2f78
commit 9f8e8e87e8
64 changed files with 7414 additions and 37 deletions
Download Patch File Download Diff File Expand all files Collapse all files

90
docs/api/models/mixins/alias-mixin.md Normal file
View File

@ -0,0 +1,90 @@
<a name="models.mixins.alias_mixin"></a>
# models.mixins.alias\_mixin
<a name="models.mixins.alias_mixin.AliasMixin"></a>
## AliasMixin Objects
```python
class AliasMixin()
```
Used to translate field names into database column names.
<a name="models.mixins.alias_mixin.AliasMixin.get_column_alias"></a>
#### get\_column\_alias
```python
| @classmethod
| get_column_alias(cls, field_name: str) -> str
```
Returns db alias (column name in db) for given ormar field.
For fields without alias field name is returned.
**Arguments**:
- `field_name (str)`: name of the field to get alias from
**Returns**:
`(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
```python
| @classmethod
| get_column_name_from_alias(cls, alias: str) -> str
```
Returns ormar field name for given db alias (column name in db).
If field do not have alias it's returned as is.
**Arguments**:
- `alias (str)`:
**Returns**:
`(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
```python
| @classmethod
| translate_columns_to_aliases(cls, new_kwargs: Dict) -> Dict
```
Translates dictionary of model fields changing field names into aliases.
If field has no alias the field name remains intact.
Only fields present in the dictionary are translated.
**Arguments**:
- `new_kwargs (Dict)`: dict with fields names and their values
**Returns**:
`(Dict)`: dict with aliases and their values
<a name="models.mixins.alias_mixin.AliasMixin.translate_aliases_to_columns"></a>
#### translate\_aliases\_to\_columns
```python
| @classmethod
| translate_aliases_to_columns(cls, new_kwargs: Dict) -> Dict
```
Translates dictionary of model fields changing aliases into field names.
If field has no alias the alias is already a field name.
Only fields present in the dictionary are translated.
**Arguments**:
- `new_kwargs (Dict)`: dict with aliases and their values
**Returns**:
`(Dict)`: dict with fields names and their values

206
docs/api/models/mixins/excludable-mixin.md Normal file
View File

@ -0,0 +1,206 @@
<a name="models.mixins.excludable_mixin"></a>
# models.mixins.excludable\_mixin
<a name="models.mixins.excludable_mixin.ExcludableMixin"></a>
## ExcludableMixin Objects
```python
class ExcludableMixin(RelationMixin)
```
Used to include/exclude given set of fields on models during load and dict() calls.
<a name="models.mixins.excludable_mixin.ExcludableMixin.get_child"></a>
#### get\_child
```python
| @staticmethod
| get_child(items: Union[Set, Dict, None], key: str = None) -> Union[Set, Dict, None]
```
Used to get nested dictionaries keys if they exists otherwise returns
passed items.
**Arguments**:
- `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
<a name="models.mixins.excludable_mixin.ExcludableMixin.get_excluded"></a>
#### get\_excluded
```python
| @staticmethod
| get_excluded(exclude: Union[Set, Dict, None], key: str = None) -> Union[Set, Dict, None]
```
Proxy to ExcludableMixin.get_child for exclusions.
**Arguments**:
- `exclude (Union[Set, Dict, None])`: bag of items to exclude
- `key (str)`: name of the child to extract
**Returns**:
`(Union[Set, Dict, None])`: child extracted from items if exists
<a name="models.mixins.excludable_mixin.ExcludableMixin.get_included"></a>
#### get\_included
```python
| @staticmethod
| get_included(include: Union[Set, Dict, None], key: str = None) -> Union[Set, Dict, None]
```
Proxy to ExcludableMixin.get_child for inclusions.
**Arguments**:
- `include (Union[Set, Dict, None])`: bag of items to include
- `key (str)`: name of the child to extract
**Returns**:
`(Union[Set, Dict, None])`: child extracted from items if exists
<a name="models.mixins.excludable_mixin.ExcludableMixin.is_excluded"></a>
#### is\_excluded
```python
| @staticmethod
| is_excluded(exclude: Union[Set, Dict, None], key: str = None) -> bool
```
Checks if given key should be excluded on model/ dict.
**Arguments**:
- `exclude (Union[Set, Dict, None])`: bag of items to exclude
- `key (str)`: name of the child to extract
**Returns**:
`(Union[Set, Dict, None])`: child extracted from items if exists
<a name="models.mixins.excludable_mixin.ExcludableMixin.is_included"></a>
#### is\_included
```python
| @staticmethod
| is_included(include: Union[Set, Dict, None], key: str = None) -> bool
```
Checks if given key should be included on model/ dict.
**Arguments**:
- `include (Union[Set, Dict, None])`: bag of items to include
- `key (str)`: name of the child to extract
**Returns**:
`(Union[Set, Dict, None])`: child extracted from items if exists
<a name="models.mixins.excludable_mixin.ExcludableMixin._populate_pk_column"></a>
#### \_populate\_pk\_column
```python
| @staticmethod
| _populate_pk_column(model: Type["Model"], columns: List[str], use_alias: bool = False) -> List[str]
```
Adds primary key column/alias (depends on use_alias flag) to list of
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
**Returns**:
`(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: Type["Model"], fields: Optional[Union[Set, Dict]], exclude_fields: Optional[Union[Set, Dict]], use_alias: bool = False) -> List[str]
```
Returns list of aliases or field names for given model.
Aliases/names switch is use_alias flag.
If provided only fields included in fields will be returned.
If provided fields in exclude_fields will be excluded in return.
Primary key field is always added and cannot be excluded (will be added anyway).
**Arguments**:
- `model (Type["Model"])`: model on columns are selected
- `fields (Optional[Union[Set, Dict]])`: set/dict of fields to include
- `exclude_fields (Optional[Union[Set, Dict]])`: set/dict of fields to exclude
- `use_alias (bool)`: flag if aliases or field names should be used
**Returns**:
`(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
```python
| @classmethod
| _update_excluded_with_related_not_required(cls, exclude: Union["AbstractSetIntStr", "MappingIntStrAny", None], nested: bool = False) -> Union[Set, Dict]
```
Used during generation of the dict().
To avoid cyclical references and max recurrence limit nested models have to
exclude related models that are not mandatory.
For a main model (not nested) only nullable related field names are added to
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**:
`(Union[Set, Dict])`: set or dict with excluded fields added.
<a name="models.mixins.excludable_mixin.ExcludableMixin.get_names_to_exclude"></a>
#### get\_names\_to\_exclude
```python
| @classmethod
| get_names_to_exclude(cls, fields: Optional[Union[Dict, Set]] = None, exclude_fields: Optional[Union[Dict, Set]] = None) -> Set
```
Returns a set of models field names that should be explicitly excluded
during model initialization.
Those fields will be set to None to avoid ormar/pydantic setting default
values on them. They should be returned as None in any case.
Used in parsing data from database rows that construct Models by initializing
them with dicts constructed from those db rows.
**Arguments**:
- `fields (Optional[Union[Set, Dict]])`: set/dict of fields to include
- `exclude_fields (Optional[Union[Set, Dict]])`: set/dict of fields to exclude
**Returns**:
`(Set)`: set of field names that should be excluded

60
docs/api/models/mixins/merge-model-mixin.md Normal file
View File

@ -0,0 +1,60 @@
<a name="models.mixins.merge_mixin"></a>
# models.mixins.merge\_mixin
<a name="models.mixins.merge_mixin.MergeModelMixin"></a>
## MergeModelMixin Objects
```python
class MergeModelMixin()
```
Used to merge models instances returned by database,
but already initialized to ormar Models.keys
Models can duplicate during joins when parent model has multiple child rows,
in the end all parent (main) models should be unique.
<a name="models.mixins.merge_mixin.MergeModelMixin.merge_instances_list"></a>
#### merge\_instances\_list
```python
| @classmethod
| merge_instances_list(cls, result_rows: Sequence["Model"]) -> Sequence["Model"]
```
Merges a list of models into list of unique models.
Models can duplicate during joins when parent model has multiple child rows,
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
**Returns**:
`(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
```python
| @classmethod
| merge_two_instances(cls, one: "Model", other: "Model") -> "Model"
```
Merges current (other) Model and previous one (one) and returns the current
Model instance with data merged from previous one.
If needed it's calling itself recurrently and merges also children models.
**Arguments**:
- `one (Model)`: previous model instance
- `other (Model)`: current model instance
**Returns**:
`(Model)`: current Model instance with data merged from previous one.

100
docs/api/models/mixins/prefetch-query-mixin.md Normal file
View File

@ -0,0 +1,100 @@
<a name="models.mixins.prefetch_mixin"></a>
# models.mixins.prefetch\_mixin
<a name="models.mixins.prefetch_mixin.PrefetchQueryMixin"></a>
## PrefetchQueryMixin Objects
```python
class PrefetchQueryMixin(RelationMixin)
```
Used in PrefetchQuery to extract ids and names of models to prefetch.
<a name="models.mixins.prefetch_mixin.PrefetchQueryMixin.get_clause_target_and_filter_column_name"></a>
#### get\_clause\_target\_and\_filter\_column\_name
```python
| @staticmethod
| get_clause_target_and_filter_column_name(parent_model: Type["Model"], target_model: Type["Model"], reverse: bool, related: str) -> Tuple[Type["Model"], str]
```
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
**Returns**:
`(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
```python
| @staticmethod
| get_column_name_for_id_extraction(parent_model: Type["Model"], reverse: bool, related: str, use_raw: bool) -> str
```
Returns name of the column that should be used to extract ids from model.
Depending on the relation side it's either primary key column of parent model
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
**Returns**:
`()`:
<a name="models.mixins.prefetch_mixin.PrefetchQueryMixin.get_related_field_name"></a>
#### get\_related\_field\_name
```python
| @classmethod
| get_related_field_name(cls, target_field: Type["BaseField"]) -> str
```
Returns name of the relation field that should be used in prefetch query.
This field is later used to register relation in prefetch query,
populate relations dict, and populate nested model in prefetch query.
**Arguments**:
- `target_field (Type[BaseField])`: relation field that should be used in prefetch
**Returns**:
`(str)`: name of the field
<a name="models.mixins.prefetch_mixin.PrefetchQueryMixin.get_filtered_names_to_extract"></a>
#### get\_filtered\_names\_to\_extract
```python
| @classmethod
| get_filtered_names_to_extract(cls, prefetch_dict: Dict) -> List
```
Returns list of related fields names that should be followed to prefetch related
models from.
List of models is translated into dict to assure each model is extracted only
once in one query, that's why this function accepts prefetch_dict not list.
Only relations from current model are returned.
**Arguments**:
- `prefetch_dict (Dict)`: dictionary of fields to extract
**Returns**:
`(List)`: list of fields names to extract

93
docs/api/models/mixins/relation-mixin.md Normal file
View File

@ -0,0 +1,93 @@
<a name="models.mixins.relation_mixin"></a>
# models.mixins.relation\_mixin
<a name="models.mixins.relation_mixin.RelationMixin"></a>
## RelationMixin Objects
```python
class RelationMixin()
```
Used to return relation fields/names etc. from given model
<a name="models.mixins.relation_mixin.RelationMixin.extract_db_own_fields"></a>
#### extract\_db\_own\_fields
```python
| @classmethod
| extract_db_own_fields(cls) -> Set
```
Returns only fields that are stored in the own database table, exclude all
related fields.
**Returns**:
`(Set)`: set of model fields with relation fields excluded
<a name="models.mixins.relation_mixin.RelationMixin.extract_related_fields"></a>
#### extract\_related\_fields
```python
| @classmethod
| extract_related_fields(cls) -> List
```
Returns List of ormar Fields for all relations declared on a model.
List is cached in cls._related_fields for quicker access.
**Returns**:
`(List)`: list of related fields
<a name="models.mixins.relation_mixin.RelationMixin.extract_related_names"></a>
#### extract\_related\_names
```python
| @classmethod
| extract_related_names(cls) -> Set
```
Returns List of fields names for all relations declared on a model.
List is cached in cls._related_names for quicker access.
**Returns**:
`(List)`: list of related fields names
<a name="models.mixins.relation_mixin.RelationMixin._extract_db_related_names"></a>
#### \_extract\_db\_related\_names
```python
| @classmethod
| _extract_db_related_names(cls) -> Set
```
Returns only fields that are stored in the own database table, exclude
related fields that are not stored as foreign keys on given model.
**Returns**:
`(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

93
docs/api/models/mixins/save-prepare-mixin.md Normal file
View File

@ -0,0 +1,93 @@
<a name="models.mixins.save_mixin"></a>
# models.mixins.save\_mixin
<a name="models.mixins.save_mixin.SavePrepareMixin"></a>
## SavePrepareMixin Objects
```python
class SavePrepareMixin(RelationMixin, AliasMixin)
```
Used to prepare models to be saved in database
<a name="models.mixins.save_mixin.SavePrepareMixin.prepare_model_to_save"></a>
#### prepare\_model\_to\_save
```python
| @classmethod
| 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,
and it's set to None.
Substitute related models with their primary key values as fk column.
Populates the default values for field with default set and no value.
Translate columns into aliases (db names).
**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
```python
| @classmethod
| _remove_pk_from_kwargs(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.substitute_models_with_pks"></a>
#### substitute\_models\_with\_pks
```python
| @classmethod
| substitute_models_with_pks(cls, model_dict: Dict) -> Dict
```
Receives dictionary of model that is about to be saved and changes all related
models that are stored as foreign keys to their fk value.
**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.populate_default_values"></a>
#### populate\_default\_values
```python
| @classmethod
| populate_default_values(cls, new_kwargs: Dict) -> Dict
```
Receives dictionary of model that is about to be saved and populates the default
value on the fields that have the default value set, but no actual value was
passed by the user.
**Arguments**:
- `new_kwargs (Dict)`: dictionary of model that is about to be saved
**Returns**:
`(Dict)`: dictionary of model that is about to be saved