diff --git a/docs/api/fields/base-field.md b/docs/api/fields/base-field.md index b30d498..49a2d9d 100644 --- a/docs/api/fields/base-field.md +++ b/docs/api/fields/base-field.md @@ -33,7 +33,7 @@ Model columns only. **Returns**: -`(bool)`: result of the check +`bool`: result of the check #### get\_alias @@ -46,8 +46,7 @@ Used to translate Model column names to database column names during db queries. **Returns**: -`(str)`: returns custom database column name if defined by user, -otherwise field name in ormar/pydantic +`str`: returns custom database column name if defined by user, #### get\_pydantic\_default @@ -62,7 +61,7 @@ Used in an ormar Model Metaclass. **Returns**: -`(pydantic.FieldInfo)`: instance of base pydantic.FieldInfo +`pydantic.FieldInfo`: instance of base pydantic.FieldInfo #### default\_value @@ -82,13 +81,12 @@ Used in converting to pydantic FieldInfo. **Arguments**: -- `use_server (bool)`: flag marking if server_default should be treated as default value, default False +- `use_server` (`bool`): flag marking if server_default should be **Returns**: -`(Optional[pydantic.FieldInfo])`: returns a call to pydantic.Field -which is returning a FieldInfo instance +`Optional[pydantic.FieldInfo]`: returns a call to pydantic.Field #### get\_default @@ -103,12 +101,12 @@ Used to populate default_values for pydantic Model in ormar Model Metaclass. **Arguments**: -- `use_server (bool)`: flag marking if server_default should be treated as default value, default False +- `use_server` (`bool`): flag marking if server_default should be **Returns**: -`(Any)`: default value for the field if set, otherwise implicit None +`Any`: default value for the field if set, otherwise implicit None #### has\_default @@ -121,12 +119,12 @@ Checks if the field has default value set. **Arguments**: -- `use_server (bool)`: flag marking if server_default should be treated as default value, default False +- `use_server` (`bool`): flag marking if server_default should be **Returns**: -`(bool)`: result of the check if default value is set +`bool`: result of the check if default value is set #### is\_auto\_primary\_key @@ -141,7 +139,7 @@ Autoincrement primary_key is nullable/optional. **Returns**: -`(bool)`: result of the check for primary key and autoincrement +`bool`: result of the check for primary key and autoincrement #### construct\_constraints @@ -156,7 +154,7 @@ And we need a new ForeignKey for subclasses of current model **Returns**: -`(List[sqlalchemy.schema.ForeignKey])`: List of sqlalchemy foreign keys - by default one. +`List[sqlalchemy.schema.ForeignKey]`: List of sqlalchemy foreign keys - by default one. #### get\_column @@ -171,11 +169,11 @@ primary_key, index, unique, nullable, default and server_default. **Arguments**: -- `name (str)`: name of the db column - used if alias is not set +- `name` (`str`): name of the db column - used if alias is not set **Returns**: -`(sqlalchemy.Column)`: actual definition of the database column as sqlalchemy requires. +`sqlalchemy.Column`: actual definition of the database column as sqlalchemy requires. #### \_get\_encrypted\_column @@ -188,11 +186,11 @@ Returns EncryptedString column type instead of actual column. **Arguments**: -- `name (str)`: column name +- `name` (`str`): column name **Returns**: -`(sqlalchemy.Column)`: newly defined column +`sqlalchemy.Column`: newly defined column #### expand\_relationship @@ -209,13 +207,13 @@ dict (from Model) or actual instance/list of a "Model". **Arguments**: -- `value (Any)`: a Model field value, returned untouched for non relation fields. -- `child (Union["Model", "NewBaseModel"])`: a child Model to register -- `to_register (bool)`: flag if the relation should be set in RelationshipManager +- `value` (`Any`): a Model field value, returned untouched for non relation fields. +- `child` (`Union["Model", "NewBaseModel"]`): a child Model to register +- `to_register` (`bool`): flag if the relation should be set in RelationshipManager **Returns**: -`(Any)`: returns untouched value for normal fields, expands only for relations +`Any`: returns untouched value for normal fields, expands only for relations #### set\_self\_reference\_flag @@ -228,7 +226,7 @@ Sets `self_reference` to True if field to and owner are same model. **Returns**: -`(None)`: None +`None`: None #### has\_unresolved\_forward\_refs @@ -242,7 +240,7 @@ model can be used. **Returns**: -`(bool)`: result of the check +`bool`: result of the check #### evaluate\_forward\_ref @@ -255,12 +253,12 @@ Evaluates the ForwardRef to actual Field based on global and local namespaces **Arguments**: -- `globalns (Any)`: global namespace -- `localns (Any)`: local namespace +- `globalns` (`Any`): global namespace +- `localns` (`Any`): local namespace **Returns**: -`(None)`: None +`None`: None #### get\_related\_name @@ -274,5 +272,5 @@ It's either set as `related_name` or by default it's owner model. get_name + 's' **Returns**: -`(str)`: name of the related_name or default related name. +`str`: name of the related_name or default related name. diff --git a/docs/api/fields/decorators.md b/docs/api/fields/decorators.md index 28e052c..4a37473 100644 --- a/docs/api/fields/decorators.md +++ b/docs/api/fields/decorators.md @@ -20,9 +20,9 @@ Note that "fields" exposed like this do not go through validation. **Arguments**: -- `func (Callable)`: decorated function to be exposed +- `func` (`Callable`): decorated function to be exposed **Returns**: -`(Union[property, Callable])`: decorated function passed in func param, with set __property_field__ = True +`Union[property, Callable]`: decorated function passed in func param, with set __property_field__ = True diff --git a/docs/api/fields/foreign-key.md b/docs/api/fields/foreign-key.md index c8ae997..892e7af 100644 --- a/docs/api/fields/foreign-key.md +++ b/docs/api/fields/foreign-key.md @@ -20,12 +20,12 @@ If the nested related Models are required they are set with -1 as pk value. **Arguments**: -- `fk (Model class)`: class of the related Model to which instance should be constructed -- `pk (Any)`: value of the primary_key column +- `fk` (`Model class`): class of the related Model to which instance should be constructed +- `pk` (`Any`): value of the primary_key column **Returns**: -`(Model)`: Model instance populated with only pk +`Model`: Model instance populated with only pk #### create\_dummy\_model @@ -39,12 +39,12 @@ Populates only pk field and set it to desired type. **Arguments**: -- `base_model (Model class)`: class of target dummy model -- `pk_field (Union[BaseField, "ForeignKeyField", "ManyToManyField"])`: ormar Field to be set on pydantic Model +- `base_model` (`Model class`): class of target dummy model +- `pk_field` (`Union[BaseField, "ForeignKeyField", "ManyToManyField"]`): ormar Field to be set on pydantic Model **Returns**: -`(pydantic.BaseModel)`: constructed dummy model +`pydantic.BaseModel`: constructed dummy model #### populate\_fk\_params\_based\_on\_to\_model @@ -58,16 +58,16 @@ pydantic field to use, ForeignKey constraint and type of the target column field **Arguments**: -- `to (Model class)`: target related ormar Model -- `nullable (bool)`: marks field as optional/ required -- `onupdate (str)`: parameter passed to sqlalchemy.ForeignKey. How to treat child rows on update of parent (the one where FK is defined) model. -- `ondelete (str)`: parameter passed to sqlalchemy.ForeignKey. How to treat child rows on delete of parent (the one where FK is defined) model. +- `to` (`Model class`): target related ormar Model +- `nullable` (`bool`): marks field as optional/ required +- `onupdate` (`str`): parameter passed to sqlalchemy.ForeignKey. +- `ondelete` (`str`): parameter passed to sqlalchemy.ForeignKey. **Returns**: -`(Tuple[Any, List, Any])`: tuple with target pydantic type, list of fk constraints and target col type +`Tuple[Any, List, Any]`: tuple with target pydantic type, list of fk constraints and target col type #### validate\_not\_allowed\_fields @@ -86,7 +86,7 @@ notify the user that it's not allowed/ supported. **Arguments**: -- `kwargs (Dict)`: dict of kwargs to verify passed to relation field +- `kwargs` (`Dict`): dict of kwargs to verify passed to relation field ## UniqueColumns Objects @@ -123,22 +123,22 @@ Accepts number of relation setting parameters as well as all BaseField ones. **Arguments**: -- `to (Model class)`: target related ormar Model -- `name (str)`: name of the database field - later called alias -- `unique (bool)`: parameter passed to sqlalchemy.ForeignKey, unique flag -- `nullable (bool)`: marks field as optional/ required -- `related_name (str)`: name of reversed FK relation populated for you on to model -- `virtual (bool)`: marks if relation is virtual. It is for reversed FK and auto generated FK on through model in Many2Many relations. -- `onupdate (str)`: parameter passed to sqlalchemy.ForeignKey. How to treat child rows on update of parent (the one where FK is defined) model. -- `ondelete (str)`: parameter passed to sqlalchemy.ForeignKey. How to treat child rows on delete of parent (the one where FK is defined) model. -- `kwargs (Any)`: all other args to be populated by BaseField +- `to` (`Model class`): target related ormar Model +- `name` (`str`): name of the database field - later called alias +- `unique` (`bool`): parameter passed to sqlalchemy.ForeignKey, unique flag +- `nullable` (`bool`): marks field as optional/ required +- `related_name` (`str`): name of reversed FK relation populated for you on to model +- `virtual` (`bool`): marks if relation is virtual. +- `onupdate` (`str`): parameter passed to sqlalchemy.ForeignKey. +- `ondelete` (`str`): parameter passed to sqlalchemy.ForeignKey. +- `kwargs` (`Any`): all other args to be populated by BaseField **Returns**: -`(ForeignKeyField)`: ormar ForeignKeyField with relation to selected model +`ForeignKeyField`: ormar ForeignKeyField with relation to selected model ## ForeignKeyField Objects @@ -162,7 +162,7 @@ It's either set as `related_name` or by default it's owner model. get_name + 's' **Returns**: -`(str)`: name of the related_name or default related name. +`str`: name of the related_name or default related name. #### get\_related\_name @@ -176,7 +176,7 @@ It's either set as `related_name` or by default it's owner model. get_name + 's' **Returns**: -`(str)`: name of the related_name or default related name. +`str`: name of the related_name or default related name. #### default\_target\_field\_name @@ -189,7 +189,7 @@ Returns default target model name on through model. **Returns**: -`(str)`: name of the field +`str`: name of the field #### default\_source\_field\_name @@ -202,7 +202,7 @@ Returns default target model name on through model. **Returns**: -`(str)`: name of the field +`str`: name of the field #### evaluate\_forward\_ref @@ -215,12 +215,12 @@ Evaluates the ForwardRef to actual Field based on global and local namespaces **Arguments**: -- `globalns (Any)`: global namespace -- `localns (Any)`: local namespace +- `globalns` (`Any`): global namespace +- `localns` (`Any`): local namespace **Returns**: -`(None)`: None +`None`: None #### \_extract\_model\_from\_sequence @@ -236,13 +236,13 @@ Used in reverse FK relations. **Arguments**: -- `value (List)`: list of Model -- `child (Model)`: child/ related Model -- `to_register (bool)`: flag if the relation should be set in RelationshipManager +- `value` (`List`): list of Model +- `child` (`Model`): child/ related Model +- `to_register` (`bool`): flag if the relation should be set in RelationshipManager **Returns**: -`(List["Model"])`: list (if needed) registered Models +`List["Model"]`: list (if needed) registered Models #### \_register\_existing\_model @@ -258,13 +258,13 @@ Used in reverse FK relations and normal FK for single models. **Arguments**: -- `value (Model)`: already instantiated Model -- `child (Model)`: child/ related Model -- `to_register (bool)`: flag if the relation should be set in RelationshipManager +- `value` (`Model`): already instantiated Model +- `child` (`Model`): child/ related Model +- `to_register` (`bool`): flag if the relation should be set in RelationshipManager **Returns**: -`(Model)`: (if needed) registered Model +`Model`: (if needed) registered Model #### \_construct\_model\_from\_dict @@ -281,13 +281,13 @@ Used in normal FK for dictionaries. **Arguments**: -- `value (dict)`: dictionary of a Model -- `child (Model)`: child/ related Model -- `to_register (bool)`: flag if the relation should be set in RelationshipManager +- `value` (`dict`): dictionary of a Model +- `child` (`Model`): child/ related Model +- `to_register` (`bool`): flag if the relation should be set in RelationshipManager **Returns**: -`(Model)`: (if needed) registered Model +`Model`: (if needed) registered Model #### \_construct\_model\_from\_pk @@ -303,13 +303,13 @@ Used in normal FK for dictionaries. **Arguments**: -- `value (Any)`: value of a related pk / fk column -- `child (Model)`: child/ related Model -- `to_register (bool)`: flag if the relation should be set in RelationshipManager +- `value` (`Any`): value of a related pk / fk column +- `child` (`Model`): child/ related Model +- `to_register` (`bool`): flag if the relation should be set in RelationshipManager **Returns**: -`(Model)`: (if needed) registered Model +`Model`: (if needed) registered Model #### register\_relation @@ -326,8 +326,8 @@ Used in Metaclass and sometimes some relations are missing **Arguments**: -- `model (Model class)`: parent model (with relation definition) -- `child (Model class)`: child model +- `model` (`Model class`): parent model (with relation definition) +- `child` (`Model class`): child model #### has\_unresolved\_forward\_refs @@ -341,7 +341,7 @@ model can be used. **Returns**: -`(bool)`: result of the check +`bool`: result of the check #### expand\_relationship @@ -359,13 +359,13 @@ Selects the appropriate constructor based on a passed value. **Arguments**: -- `value (Any)`: a Model field value, returned untouched for non relation fields. -- `child (Union["Model", "NewBaseModel"])`: a child Model to register -- `to_register (bool)`: flag if the relation should be set in RelationshipManager +- `value` (`Any`): a Model field value, returned untouched for non relation fields. +- `child` (`Union["Model", "NewBaseModel"]`): a child Model to register +- `to_register` (`bool`): flag if the relation should be set in RelationshipManager **Returns**: -`(Optional[Union["Model", List["Model"]]])`: returns a Model or a list of Models +`Optional[Union["Model", List["Model"]]]`: returns a Model or a list of Models #### get\_relation\_name @@ -379,7 +379,7 @@ names for m2m models **Returns**: -`(bool)`: result of the check +`bool`: result of the check #### get\_source\_model @@ -392,5 +392,5 @@ Returns model from which the relation comes -> either owner or through model **Returns**: -`(Type["Model"])`: source model +`Type["Model"]`: source model diff --git a/docs/api/fields/many-to-many.md b/docs/api/fields/many-to-many.md index de80987..d80989e 100644 --- a/docs/api/fields/many-to-many.md +++ b/docs/api/fields/many-to-many.md @@ -12,7 +12,7 @@ Verifies if the through model does not have relations. **Arguments**: -- `through (Type['Model])`: through Model to be checked +- `through` (`Type['Model]`): through Model to be checked #### populate\_m2m\_params\_based\_on\_to\_model @@ -26,12 +26,12 @@ pydantic field to use and type of the target column field. **Arguments**: -- `to (Model class)`: target related ormar Model -- `nullable (bool)`: marks field as optional/ required +- `to` (`Model class`): target related ormar Model +- `nullable` (`bool`): marks field as optional/ required **Returns**: -`(tuple with target pydantic type and target col type)`: Tuple[List, Any] +`tuple with target pydantic type and target col type`: Tuple[List, Any] #### ManyToMany @@ -48,17 +48,17 @@ Accepts number of relation setting parameters as well as all BaseField ones. **Arguments**: -- `to (Model class)`: target related ormar Model -- `through (Model class)`: through model for m2m relation -- `name (str)`: name of the database field - later called alias -- `unique (bool)`: parameter passed to sqlalchemy.ForeignKey, unique flag -- `virtual (bool)`: marks if relation is virtual. It is for reversed FK and auto generated FK on through model in Many2Many relations. -- `kwargs (Any)`: all other args to be populated by BaseField +- `to` (`Model class`): target related ormar Model +- `through` (`Model class`): through model for m2m relation +- `name` (`str`): name of the database field - later called alias +- `unique` (`bool`): parameter passed to sqlalchemy.ForeignKey, unique flag +- `virtual` (`bool`): marks if relation is virtual. +- `kwargs` (`Any`): all other args to be populated by BaseField **Returns**: -`(ManyToManyField)`: ormar ManyToManyField with m2m relation to selected model +`ManyToManyField`: ormar ManyToManyField with m2m relation to selected model ## ManyToManyField Objects @@ -82,7 +82,7 @@ It's either set as `related_name` or by default it's field name. **Returns**: -`(str)`: name of the related_name or default related name. +`str`: name of the related_name or default related name. #### has\_unresolved\_forward\_refs @@ -96,7 +96,7 @@ model can be used. **Returns**: -`(bool)`: result of the check +`bool`: result of the check #### evaluate\_forward\_ref @@ -109,12 +109,12 @@ Evaluates the ForwardRef to actual Field based on global and local namespaces **Arguments**: -- `globalns (Any)`: global namespace -- `localns (Any)`: local namespace +- `globalns` (`Any`): global namespace +- `localns` (`Any`): local namespace **Returns**: -`(None)`: None +`None`: None #### get\_relation\_name @@ -128,7 +128,7 @@ names for m2m models **Returns**: -`(bool)`: result of the check +`bool`: result of the check #### get\_source\_model @@ -141,7 +141,7 @@ Returns model from which the relation comes -> either owner or through model **Returns**: -`(Type["Model"])`: source model +`Type["Model"]`: source model #### create\_default\_through\_model diff --git a/docs/api/fields/model-fields.md b/docs/api/fields/model-fields.md index cf2e341..3d4162b 100644 --- a/docs/api/fields/model-fields.md +++ b/docs/api/fields/model-fields.md @@ -12,14 +12,14 @@ Checks if the given field should be nullable/ optional based on parameters given **Arguments**: -- `nullable (Optional[bool])`: flag explicit setting a column as nullable -- `default (Any)`: value or function to be called as default in python -- `server_default (Any)`: function to be called as default by sql server -- `pydantic_only (Optional[bool])`: flag if fields should not be included in the sql table +- `nullable` (`Optional[bool]`): flag explicit setting a column as nullable +- `default` (`Any`): value or function to be called as default in python +- `server_default` (`Any`): function to be called as default by sql server +- `pydantic_only` (`Optional[bool]`): flag if fields should not be included in the sql table **Returns**: -`(bool)`: result of the check +`bool`: result of the check #### is\_auto\_primary\_key @@ -32,12 +32,12 @@ Checks if field is an autoincrement pk -> if yes it's optional. **Arguments**: -- `primary_key (bool)`: flag if field is a pk field -- `autoincrement (bool)`: flag if field should be autoincrement +- `primary_key` (`bool`): flag if field is a pk field +- `autoincrement` (`bool`): flag if field should be autoincrement **Returns**: -`(bool)`: result of the check +`bool`: result of the check ## ModelFieldFactory Objects @@ -61,11 +61,11 @@ Accepts required and optional parameters that each column type accepts. **Arguments**: -- `kwargs (Any)`: key, value pairs of sqlalchemy options +- `kwargs` (`Any`): key, value pairs of sqlalchemy options **Returns**: -`(sqlalchemy Column)`: initialized column with proper options +`sqlalchemy Column`: initialized column with proper options #### validate @@ -79,7 +79,7 @@ Used to validate if all required parameters on a given field type are set. **Arguments**: -- `kwargs (Any)`: all params passed during construction +- `kwargs` (`Any`): all params passed during construction ## String Objects @@ -103,11 +103,11 @@ Accepts required and optional parameters that each column type accepts. **Arguments**: -- `kwargs (Any)`: key, value pairs of sqlalchemy options +- `kwargs` (`Any`): key, value pairs of sqlalchemy options **Returns**: -`(sqlalchemy Column)`: initialized column with proper options +`sqlalchemy Column`: initialized column with proper options #### validate @@ -121,7 +121,7 @@ Used to validate if all required parameters on a given field type are set. **Arguments**: -- `kwargs (Any)`: all params passed during construction +- `kwargs` (`Any`): all params passed during construction ## Integer Objects @@ -145,11 +145,11 @@ Accepts required and optional parameters that each column type accepts. **Arguments**: -- `kwargs (Any)`: key, value pairs of sqlalchemy options +- `kwargs` (`Any`): key, value pairs of sqlalchemy options **Returns**: -`(sqlalchemy Column)`: initialized column with proper options +`sqlalchemy Column`: initialized column with proper options ## Text Objects @@ -173,11 +173,11 @@ Accepts required and optional parameters that each column type accepts. **Arguments**: -- `kwargs (Any)`: key, value pairs of sqlalchemy options +- `kwargs` (`Any`): key, value pairs of sqlalchemy options **Returns**: -`(sqlalchemy Column)`: initialized column with proper options +`sqlalchemy Column`: initialized column with proper options ## Float Objects @@ -201,11 +201,11 @@ Accepts required and optional parameters that each column type accepts. **Arguments**: -- `kwargs (Any)`: key, value pairs of sqlalchemy options +- `kwargs` (`Any`): key, value pairs of sqlalchemy options **Returns**: -`(sqlalchemy Column)`: initialized column with proper options +`sqlalchemy Column`: initialized column with proper options ## DateTime Objects @@ -229,11 +229,11 @@ Accepts required and optional parameters that each column type accepts. **Arguments**: -- `kwargs (Any)`: key, value pairs of sqlalchemy options +- `kwargs` (`Any`): key, value pairs of sqlalchemy options **Returns**: -`(sqlalchemy Column)`: initialized column with proper options +`sqlalchemy Column`: initialized column with proper options ## Date Objects @@ -257,11 +257,11 @@ Accepts required and optional parameters that each column type accepts. **Arguments**: -- `kwargs (Any)`: key, value pairs of sqlalchemy options +- `kwargs` (`Any`): key, value pairs of sqlalchemy options **Returns**: -`(sqlalchemy Column)`: initialized column with proper options +`sqlalchemy Column`: initialized column with proper options ## Time Objects @@ -285,11 +285,11 @@ Accepts required and optional parameters that each column type accepts. **Arguments**: -- `kwargs (Any)`: key, value pairs of sqlalchemy options +- `kwargs` (`Any`): key, value pairs of sqlalchemy options **Returns**: -`(sqlalchemy Column)`: initialized column with proper options +`sqlalchemy Column`: initialized column with proper options ## JSON Objects @@ -313,11 +313,11 @@ Accepts required and optional parameters that each column type accepts. **Arguments**: -- `kwargs (Any)`: key, value pairs of sqlalchemy options +- `kwargs` (`Any`): key, value pairs of sqlalchemy options **Returns**: -`(sqlalchemy Column)`: initialized column with proper options +`sqlalchemy Column`: initialized column with proper options ## BigInteger Objects @@ -341,11 +341,11 @@ Accepts required and optional parameters that each column type accepts. **Arguments**: -- `kwargs (Any)`: key, value pairs of sqlalchemy options +- `kwargs` (`Any`): key, value pairs of sqlalchemy options **Returns**: -`(sqlalchemy Column)`: initialized column with proper options +`sqlalchemy Column`: initialized column with proper options ## Decimal Objects @@ -369,11 +369,11 @@ Accepts required and optional parameters that each column type accepts. **Arguments**: -- `kwargs (Any)`: key, value pairs of sqlalchemy options +- `kwargs` (`Any`): key, value pairs of sqlalchemy options **Returns**: -`(sqlalchemy Column)`: initialized column with proper options +`sqlalchemy Column`: initialized column with proper options #### validate @@ -387,7 +387,7 @@ Used to validate if all required parameters on a given field type are set. **Arguments**: -- `kwargs (Any)`: all params passed during construction +- `kwargs` (`Any`): all params passed during construction ## UUID Objects @@ -411,9 +411,9 @@ Accepts required and optional parameters that each column type accepts. **Arguments**: -- `kwargs (Any)`: key, value pairs of sqlalchemy options +- `kwargs` (`Any`): key, value pairs of sqlalchemy options **Returns**: -`(sqlalchemy Column)`: initialized column with proper options +`sqlalchemy Column`: initialized column with proper options diff --git a/docs/api/models/descriptors/descriptors.md b/docs/api/models/descriptors/descriptors.md new file mode 100644 index 0000000..c0b9d3c --- /dev/null +++ b/docs/api/models/descriptors/descriptors.md @@ -0,0 +1,62 @@ + +# models.descriptors.descriptors + + +## PydanticDescriptor Objects + +```python +class PydanticDescriptor() +``` + +Pydantic descriptor simply delegates everything to pydantic model + + +## JsonDescriptor Objects + +```python +class JsonDescriptor() +``` + +Json descriptor dumps/loads strings to actual data on write/read + + +## BytesDescriptor Objects + +```python +class BytesDescriptor() +``` + +Bytes descriptor converts strings to bytes on write and converts bytes to str +if represent_as_base64_str flag is set, so the value can be dumped to json + + +## PkDescriptor Objects + +```python +class PkDescriptor() +``` + +As of now it's basically a copy of PydanticDescriptor but that will +change in the future with multi column primary keys + + +## RelationDescriptor Objects + +```python +class RelationDescriptor() +``` + +Relation descriptor expands the relation to initialize the related model +before setting it to __dict__. Note that expanding also registers the +related model in RelationManager. + + +## PropertyDescriptor Objects + +```python +class PropertyDescriptor() +``` + +Property descriptor handles methods decorated with @property_field decorator. +They are read only. + diff --git a/docs/api/models/excludable-items.md b/docs/api/models/excludable-items.md index ee12586..d164035 100644 --- a/docs/api/models/excludable-items.md +++ b/docs/api/models/excludable-items.md @@ -22,7 +22,7 @@ Return copy of self to avoid in place modifications **Returns**: -`(ormar.models.excludable.Excludable)`: copy of self with copied sets +`ormar.models.excludable.Excludable`: copy of self with copied sets #### set\_values @@ -35,8 +35,8 @@ Appends the data to include/exclude sets. **Arguments**: -- `value (set)`: set of values to add -- `is_exclude (bool)`: flag if values are to be excluded or included +- `value` (`set`): set of values to add +- `is_exclude` (`bool`): flag if values are to be excluded or included #### is\_included @@ -49,11 +49,11 @@ Check if field in included (in set or set is {...}) **Arguments**: -- `key (str)`: key to check +- `key` (`str`): key to check **Returns**: -`(bool)`: result of the check +`bool`: result of the check #### is\_excluded @@ -66,11 +66,11 @@ Check if field in excluded (in set or set is {...}) **Arguments**: -- `key (str)`: key to check +- `key` (`str`): key to check **Returns**: -`(bool)`: result of the check +`bool`: result of the check ## ExcludableItems Objects @@ -95,11 +95,20 @@ Copy passed ExcludableItems to avoid inplace modifications. **Arguments**: -- `other (ormar.models.excludable.ExcludableItems)`: other excludable items to be copied +- `other` (`ormar.models.excludable.ExcludableItems`): other excludable items to be copied **Returns**: -`(ormar.models.excludable.ExcludableItems)`: copy of other +`ormar.models.excludable.ExcludableItems`: copy of other + + +#### include\_entry\_count + +```python + | include_entry_count() -> int +``` + +Returns count of include items inside #### get @@ -112,12 +121,12 @@ Return Excludable for given model and alias. **Arguments**: -- `model_cls (ormar.models.metaclass.ModelMetaclass)`: target model to check -- `alias (str)`: table alias from relation manager +- `model_cls` (`ormar.models.metaclass.ModelMetaclass`): target model to check +- `alias` (`str`): table alias from relation manager **Returns**: -`(ormar.models.excludable.Excludable)`: Excludable for given model and alias +`ormar.models.excludable.Excludable`: Excludable for given model and alias #### build @@ -133,9 +142,9 @@ Each excludable has two sets of values - one to include, one to exclude. **Arguments**: -- `items (Union[List[str], str, Tuple[str], Set[str], Dict])`: values to be included or excluded -- `model_cls (ormar.models.metaclass.ModelMetaclass)`: source model from which relations are constructed -- `is_exclude (bool)`: flag if items should be included or excluded +- `items` (`Union[List[str], str, Tuple[str], Set[str], Dict]`): values to be included or excluded +- `model_cls` (`ormar.models.metaclass.ModelMetaclass`): source model from which relations are constructed +- `is_exclude` (`bool`): flag if items should be included or excluded #### \_set\_excludes @@ -148,10 +157,10 @@ Sets set of values to be included or excluded for given key and model. **Arguments**: -- `items (set)`: items to include/exclude -- `model_name (str)`: name of model to construct key -- `is_exclude (bool)`: flag if values should be included or excluded -- `alias (str)`: +- `items` (`set`): items to include/exclude +- `model_name` (`str`): name of model to construct key +- `is_exclude` (`bool`): flag if values should be included or excluded +- `alias` (`str`): #### \_traverse\_dict @@ -164,12 +173,12 @@ Goes through dict of nested values and construct/update Excludables. **Arguments**: -- `values (Dict)`: items to include/exclude -- `source_model (ormar.models.metaclass.ModelMetaclass)`: source model from which relations are constructed -- `model_cls (ormar.models.metaclass.ModelMetaclass)`: model from which current relation is constructed -- `is_exclude (bool)`: flag if values should be included or excluded -- `related_items (List)`: list of names of related fields chain -- `alias (str)`: alias of relation +- `values` (`Dict`): items to include/exclude +- `source_model` (`ormar.models.metaclass.ModelMetaclass`): source model from which relations are constructed +- `model_cls` (`ormar.models.metaclass.ModelMetaclass`): model from which current relation is constructed +- `is_exclude` (`bool`): flag if values should be included or excluded +- `related_items` (`List`): list of names of related fields chain +- `alias` (`str`): alias of relation #### \_traverse\_list @@ -182,7 +191,7 @@ Goes through list of values and construct/update Excludables. **Arguments**: -- `values (set)`: items to include/exclude -- `model_cls (ormar.models.metaclass.ModelMetaclass)`: model from which current relation is constructed -- `is_exclude (bool)`: flag if values should be included or excluded +- `values` (`set`): items to include/exclude +- `model_cls` (`ormar.models.metaclass.ModelMetaclass`): model from which current relation is constructed +- `is_exclude` (`bool`): flag if values should be included or excluded diff --git a/docs/api/models/helpers/models.md b/docs/api/models/helpers/models.md index 328a95c..e27e9e6 100644 --- a/docs/api/models/helpers/models.md +++ b/docs/api/models/helpers/models.md @@ -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 #### 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 #### 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 #### 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 #### 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 #### 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 #### 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 diff --git a/docs/api/models/helpers/pydantic.md b/docs/api/models/helpers/pydantic.md index 2788e90..6e940c1 100644 --- a/docs/api/models/helpers/pydantic.md +++ b/docs/api/models/helpers/pydantic.md @@ -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 #### 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 #### 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 #### 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. #### 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 + + +#### 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"]`): diff --git a/docs/api/models/helpers/related-names-validation.md b/docs/api/models/helpers/related-names-validation.md index 9fa93cc..1e0ee74 100644 --- a/docs/api/models/helpers/related-names-validation.md +++ b/docs/api/models/helpers/related-names-validation.md @@ -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`): diff --git a/docs/api/models/helpers/relations.md b/docs/api/models/helpers/relations.md index 025356b..7ec1e30 100644 --- a/docs/api/models/helpers/relations.md +++ b/docs/api/models/helpers/relations.md @@ -17,7 +17,7 @@ aliases for proper sql joins. **Arguments**: -- `field (ForeignKey class)`: relation field +- `field` (`ForeignKey class`): relation field #### 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 #### 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 #### 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 #### 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 #### 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 #### 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 #### 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 #### 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 diff --git a/docs/api/models/helpers/sqlalchemy.md b/docs/api/models/helpers/sqlalchemy.md index 8738404..87b66ff 100644 --- a/docs/api/models/helpers/sqlalchemy.md +++ b/docs/api/models/helpers/sqlalchemy.md @@ -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 #### 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 #### 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 #### 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 #### \_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 #### \_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 #### \_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 #### 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 #### 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 #### 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 #### 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 diff --git a/docs/api/models/helpers/validation.md b/docs/api/models/helpers/validation.md index 5c38665..8c8b481 100644 --- a/docs/api/models/helpers/validation.md +++ b/docs/api/models/helpers/validation.md @@ -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 #### 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 #### 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 #### 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 + + +#### 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 + + +#### 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 + + +#### 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 + + +#### 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 + + +#### 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 + + +#### 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 + + +#### 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 #### 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 + + +#### 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 #### 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 diff --git a/docs/api/models/mixins/alias-mixin.md b/docs/api/models/mixins/alias-mixin.md index c3a48a4..7d21457 100644 --- a/docs/api/models/mixins/alias-mixin.md +++ b/docs/api/models/mixins/alias-mixin.md @@ -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 #### 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) #### 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 #### 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 diff --git a/docs/api/models/mixins/excludable-mixin.md b/docs/api/models/mixins/excludable-mixin.md index 7731a62..e153739 100644 --- a/docs/api/models/mixins/excludable-mixin.md +++ b/docs/api/models/mixins/excludable-mixin.md @@ -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 #### \_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 #### 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 #### \_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. + + +#### \_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 #### 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 diff --git a/docs/api/models/mixins/merge-model-mixin.md b/docs/api/models/mixins/merge-model-mixin.md index d6e28f9..83f3a95 100644 --- a/docs/api/models/mixins/merge-model-mixin.md +++ b/docs/api/models/mixins/merge-model-mixin.md @@ -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 #### 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. #### \_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 diff --git a/docs/api/models/mixins/prefetch-query-mixin.md b/docs/api/models/mixins/prefetch-query-mixin.md index d4eadc2..fd911a7 100644 --- a/docs/api/models/mixins/prefetch-query-mixin.md +++ b/docs/api/models/mixins/prefetch-query-mixin.md @@ -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 #### 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**: -`()`: + #### 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 #### 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 diff --git a/docs/api/models/mixins/relation-mixin.md b/docs/api/models/mixins/relation-mixin.md index 9859f90..87ea462 100644 --- a/docs/api/models/mixins/relation-mixin.md +++ b/docs/api/models/mixins/relation-mixin.md @@ -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 #### 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 #### 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 #### 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 #### \_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 #### \_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 #### \_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 diff --git a/docs/api/models/mixins/save-prepare-mixin.md b/docs/api/models/mixins/save-prepare-mixin.md index c03daf3..02899d2 100644 --- a/docs/api/models/mixins/save-prepare-mixin.md +++ b/docs/api/models/mixins/save-prepare-mixin.md @@ -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 #### \_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 #### \_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 #### 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 #### 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 #### 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 #### 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 #### \_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 #### \_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 #### \_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 + + +#### \_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 diff --git a/docs/api/models/model-metaclass.md b/docs/api/models/model-metaclass.md index ab65c2a..1dff6a1 100644 --- a/docs/api/models/model-metaclass.md +++ b/docs/api/models/model-metaclass.md @@ -30,7 +30,7 @@ All properties here are used as "cache" to not recalculate them constantly. **Arguments**: -- `new_model (Model class)`: newly constructed Model +- `new_model` (`Model class`): newly constructed Model #### add\_property\_fields @@ -47,8 +47,8 @@ Names of property fields are cached for quicker access / extraction. **Arguments**: -- `new_model (Model class)`: newly constructed model -- `attrs (Dict[str, str])`: +- `new_model` (`Model class`): newly constructed model +- `attrs` (`Dict[str, str]`): #### register\_signals @@ -64,7 +64,7 @@ Signals are emitted in both model own methods and in selected queryset ones. **Arguments**: -- `new_model (Model class)`: newly constructed model +- `new_model` (`Model class`): newly constructed model #### verify\_constraint\_names @@ -79,9 +79,9 @@ Table creation. **Arguments**: -- `base_class (Model or model parent class)`: one of the parent classes -- `model_fields (Dict[str, BaseField])`: ormar fields in defined in current class -- `parent_value (List)`: list of base class constraints +- `base_class` (`Model or model parent class`): one of the parent classes +- `model_fields` (`Dict[str, BaseField]`): ormar fields in defined in current class +- `parent_value` (`List`): list of base class constraints #### update\_attrs\_from\_base\_meta @@ -94,9 +94,9 @@ Updates Meta parameters in child from parent if needed. **Arguments**: -- `base_class (Model or model parent class)`: one of the parent classes -- `attrs (Dict)`: new namespace for class being constructed -- `model_fields (Dict[str, BaseField])`: ormar fields in defined in current class +- `base_class` (`Model or model parent class`): one of the parent classes +- `attrs` (`Dict`): new namespace for class being constructed +- `model_fields` (`Dict[str, BaseField]`): ormar fields in defined in current class #### copy\_and\_replace\_m2m\_through\_model @@ -118,13 +118,13 @@ Removes the original sqlalchemy table from metadata if it was not removed. **Arguments**: -- `base_class (Type["Model"])`: base class model -- `field (ManyToManyField)`: field with relations definition -- `field_name (str)`: name of the relation field -- `table_name (str)`: name of the table -- `parent_fields (Dict)`: dictionary of fields to copy to new models from parent -- `attrs (Dict)`: new namespace for class being constructed -- `meta (ModelMeta)`: metaclass of currently created model +- `base_class` (`Type["Model"]`): base class model +- `field` (`ManyToManyField`): field with relations definition +- `field_name` (`str`): name of the relation field +- `table_name` (`str`): name of the table +- `parent_fields` (`Dict`): dictionary of fields to copy to new models from parent +- `attrs` (`Dict`): new namespace for class being constructed +- `meta` (`ModelMeta`): metaclass of currently created model #### copy\_data\_from\_parent\_model @@ -133,7 +133,7 @@ Removes the original sqlalchemy table from metadata if it was not removed. copy_data_from_parent_model(base_class: Type["Model"], curr_class: type, attrs: Dict, model_fields: Dict[str, Union[BaseField, ForeignKeyField, ManyToManyField]]) -> Tuple[Dict, Dict] ``` -Copy the key parameters [databse, metadata, property_fields and constraints] +Copy the key parameters [database, metadata, property_fields and constraints] and fields from parent models. Overwrites them if needed. Only abstract classes can be subclassed. @@ -147,14 +147,14 @@ Since relation fields requires different related_name for different children **Arguments**: -- `base_class (Model or model parent class)`: one of the parent classes -- `curr_class (Model or model parent class)`: current constructed class -- `attrs (Dict)`: new namespace for class being constructed -- `model_fields (Dict[str, BaseField])`: ormar fields in defined in current class +- `base_class` (`Model or model parent class`): one of the parent classes +- `curr_class` (`Model or model parent class`): current constructed class +- `attrs` (`Dict`): new namespace for class being constructed +- `model_fields` (`Dict[str, BaseField]`): ormar fields in defined in current class **Returns**: -`(Tuple[Dict, Dict])`: updated attrs and model_fields +`Tuple[Dict, Dict]`: updated attrs and model_fields #### extract\_from\_parents\_definition @@ -163,7 +163,7 @@ Since relation fields requires different related_name for different children extract_from_parents_definition(base_class: type, curr_class: type, attrs: Dict, model_fields: Dict[str, Union[BaseField, ForeignKeyField, ManyToManyField]]) -> Tuple[Dict, Dict] ``` -Extracts fields from base classes if they have valid oramr fields. +Extracts fields from base classes if they have valid ormar fields. If model was already parsed -> fields definitions need to be removed from class cause pydantic complains about field re-definition so after first child @@ -176,14 +176,14 @@ If the class is a ormar.Model it is skipped. **Arguments**: -- `base_class (Model or model parent class)`: one of the parent classes -- `curr_class (Model or model parent class)`: current constructed class -- `attrs (Dict)`: new namespace for class being constructed -- `model_fields (Dict[str, BaseField])`: ormar fields in defined in current class +- `base_class` (`Model or model parent class`): one of the parent classes +- `curr_class` (`Model or model parent class`): current constructed class +- `attrs` (`Dict`): new namespace for class being constructed +- `model_fields` (`Dict[str, BaseField]`): ormar fields in defined in current class **Returns**: -`(Tuple[Dict, Dict])`: updated attrs and model_fields +`Tuple[Dict, Dict]`: updated attrs and model_fields #### update\_attrs\_and\_fields @@ -197,11 +197,28 @@ as well as model.Meta.model_fields definitions from parents. **Arguments**: -- `attrs (Dict)`: new namespace for class being constructed -- `new_attrs (Dict)`: related of the namespace extracted from parent class -- `model_fields (Dict[str, BaseField])`: ormar fields in defined in current class -- `new_model_fields (Dict[str, BaseField])`: ormar fields defined in parent classes -- `new_fields (Set[str])`: set of new fields names +- `attrs` (`Dict`): new namespace for class being constructed +- `new_attrs` (`Dict`): related of the namespace extracted from parent class +- `model_fields` (`Dict[str, BaseField]`): ormar fields in defined in current class +- `new_model_fields` (`Dict[str, BaseField]`): ormar fields defined in parent classes +- `new_fields` (`Set[str]`): set of new fields names + + +#### add\_field\_descriptor + +```python +add_field_descriptor(name: str, field: "BaseField", new_model: Type["Model"]) -> None +``` + +Sets appropriate descriptor for each model field. +There are 5 main types of descriptors, for bytes, json, pure pydantic fields, +and 2 ormar ones - one for relation and one for pk shortcut + +**Arguments**: + +- `name` (`str`): name of the field +- `field` (`BaseField`): model field to add descriptor for +- `new_model` (`Type["Model]`): model with fields ## ModelMetaclass Objects @@ -241,7 +258,25 @@ If class has Meta class declared (so actual ormar Models) it also: **Arguments**: -- `name (str)`: name of current class -- `bases (Tuple)`: base classes -- `attrs (Dict)`: class namespace +- `name` (`str`): name of current class +- `bases` (`Tuple`): base classes +- `attrs` (`Dict`): class namespace + + +#### \_\_getattr\_\_ + +```python + | __getattr__(item: str) -> Any +``` + +Returns FieldAccessors on access to model fields from a class, +that way it can be used in python style filters and order_by. + +**Arguments**: + +- `item` (`str`): name of the field + +**Returns**: + +`FieldAccessor`: FieldAccessor for given field diff --git a/docs/api/models/model-row.md b/docs/api/models/model-row.md index 3483d50..923ee85 100644 --- a/docs/api/models/model-row.md +++ b/docs/api/models/model-row.md @@ -30,19 +30,19 @@ nested models in result. **Arguments**: -- `used_prefixes (List[str])`: list of already extracted prefixes -- `proxy_source_model (Optional[Type["ModelRow"]])`: source model from which querysetproxy is constructed -- `excludable (ExcludableItems)`: structure of fields to include and exclude -- `current_relation_str (str)`: name of the relation field -- `source_model (Type[Model])`: model on which relation was defined -- `row (sqlalchemy.engine.result.ResultProxy)`: raw result row from the database -- `select_related (List)`: list of names of related models fetched from database -- `related_models (Union[List, Dict])`: list or dict of related models -- `related_field (ForeignKeyField)`: field with relation declaration +- `used_prefixes` (`List[str]`): list of already extracted prefixes +- `proxy_source_model` (`Optional[Type["ModelRow"]]`): source model from which querysetproxy is constructed +- `excludable` (`ExcludableItems`): structure of fields to include and exclude +- `current_relation_str` (`str`): name of the relation field +- `source_model` (`Type[Model]`): model on which relation was defined +- `row` (`sqlalchemy.engine.result.ResultProxy`): raw result row from the database +- `select_related` (`List`): list of names of related models fetched from database +- `related_models` (`Union[List, Dict]`): list or dict of related models +- `related_field` (`ForeignKeyField`): field with relation declaration **Returns**: -`(Optional[Model])`: returns model if model is populated from database +`Optional[Model]`: returns model if model is populated from database #### \_process\_table\_prefix @@ -54,14 +54,14 @@ nested models in result. **Arguments**: -- `source_model (Type[Model])`: model on which relation was defined -- `current_relation_str (str)`: current relation string -- `related_field ("ForeignKeyField")`: field with relation declaration -- `used_prefixes (List[str])`: list of already extracted prefixes +- `source_model` (`Type[Model]`): model on which relation was defined +- `current_relation_str` (`str`): current relation string +- `related_field` (`"ForeignKeyField"`): field with relation declaration +- `used_prefixes` (`List[str]`): list of already extracted prefixes **Returns**: -`(str)`: table_prefix to use +`str`: table_prefix to use #### \_populate\_nested\_models\_from\_row @@ -82,18 +82,17 @@ instances. In the end those instances are added to the final model dictionary. **Arguments**: -- `proxy_source_model (Optional[Type["ModelRow"]])`: source model from which querysetproxy is constructed -- `excludable (ExcludableItems)`: structure of fields to include and exclude -- `source_model (Type[Model])`: source model from which relation started -- `current_relation_str (str)`: joined related parts into one string -- `item (Dict)`: dictionary of already populated nested models, otherwise empty dict -- `row (sqlalchemy.engine.result.ResultProxy)`: raw result row from the database -- `related_models (Union[Dict, List])`: list or dict of related models +- `proxy_source_model` (`Optional[Type["ModelRow"]]`): source model from which querysetproxy is constructed +- `excludable` (`ExcludableItems`): structure of fields to include and exclude +- `source_model` (`Type[Model]`): source model from which relation started +- `current_relation_str` (`str`): joined related parts into one string +- `item` (`Dict`): dictionary of already populated nested models, otherwise empty dict +- `row` (`sqlalchemy.engine.result.ResultProxy`): raw result row from the database +- `related_models` (`Union[Dict, List]`): list or dict of related models **Returns**: -`(Dict)`: dictionary with keys corresponding to model fields names -and values are database values +`Dict`: dictionary with keys corresponding to model fields names #### \_process\_remainder\_and\_relation\_string @@ -107,9 +106,9 @@ Process remainder models and relation string **Arguments**: -- `related_models (Union[Dict, List])`: list or dict of related models -- `current_relation_str (Optional[str])`: current relation string -- `related (str)`: name of the relation +- `related_models` (`Union[Dict, List]`): list or dict of related models +- `current_relation_str` (`Optional[str]`): current relation string +- `related` (`str`): name of the relation #### \_populate\_through\_instance @@ -124,12 +123,12 @@ Normally it's child class, unless the query is from queryset. **Arguments**: -- `row (sqlalchemy.engine.ResultProxy)`: row from db result -- `item (Dict)`: parent item dict -- `related (str)`: current relation name -- `excludable (ExcludableItems)`: structure of fields to include and exclude -- `child ("Model")`: child item of parent -- `proxy_source_model (Type["Model"])`: source model from which querysetproxy is constructed +- `row` (`sqlalchemy.engine.ResultProxy`): row from db result +- `item` (`Dict`): parent item dict +- `related` (`str`): current relation name +- `excludable` (`ExcludableItems`): structure of fields to include and exclude +- `child` (`"Model"`): child item of parent +- `proxy_source_model` (`Type["Model"]`): source model from which querysetproxy is constructed #### \_create\_through\_instance @@ -144,14 +143,14 @@ Excluded all relation fields and other exclude/include set in excludable. **Arguments**: -- `row (sqlalchemy.engine.ResultProxy)`: loaded row from database -- `through_name (str)`: name of the through field -- `related (str)`: name of the relation -- `excludable (ExcludableItems)`: structure of fields to include and exclude +- `row` (`sqlalchemy.engine.ResultProxy`): loaded row from database +- `through_name` (`str`): name of the through field +- `related` (`str`): name of the relation +- `excludable` (`ExcludableItems`): structure of fields to include and exclude **Returns**: -`("ModelRow")`: initialized through model without relation +`"ModelRow"`: initialized through model without relation #### extract\_prefixed\_table\_columns @@ -174,15 +173,14 @@ Used in Model.from_row and PrefetchQuery._populate_rows methods. **Arguments**: -- `excludable (ExcludableItems)`: structure of fields to include and exclude -- `item (Dict)`: dictionary of already populated nested models, otherwise empty dict -- `row (sqlalchemy.engine.result.ResultProxy)`: raw result row from the database -- `table_prefix (str)`: prefix of the table from AliasManager each pair of tables have own prefix (two of them depending on direction) - used in joins to allow multiple joins to the same table. +- `excludable` (`ExcludableItems`): structure of fields to include and exclude +- `item` (`Dict`): dictionary of already populated nested models, otherwise empty dict +- `row` (`sqlalchemy.engine.result.ResultProxy`): raw result row from the database +- `table_prefix` (`str`): prefix of the table from AliasManager **Returns**: -`(Dict)`: dictionary with keys corresponding to model fields names -and values are database values +`Dict`: dictionary with keys corresponding to model fields names diff --git a/docs/api/models/model-table-proxy.md b/docs/api/models/model-table-proxy.md index eb79f52..68ec34b 100644 --- a/docs/api/models/model-table-proxy.md +++ b/docs/api/models/model-table-proxy.md @@ -6,7 +6,11 @@ ```python class ModelTableProxy( - PrefetchQueryMixin, MergeModelMixin, SavePrepareMixin, ExcludableMixin) + PrefetchQueryMixin, + MergeModelMixin, + SavePrepareMixin, + ExcludableMixin, + PydanticMixin) ``` Used to combine all mixins with different set of functionalities. diff --git a/docs/api/models/model.md b/docs/api/models/model.md index a086dc4..124565b 100644 --- a/docs/api/models/model.md +++ b/docs/api/models/model.md @@ -21,11 +21,11 @@ For save kwargs are ignored, used only in update if provided. **Arguments**: -- `kwargs (Any)`: list of fields to update +- `kwargs` (`Any`): list of fields to update **Returns**: -`(Model)`: saved Model +`Model`: saved Model #### save @@ -54,7 +54,7 @@ Sets model save status to True. **Returns**: -`(Model)`: saved Model +`Model`: saved Model #### save\_related @@ -79,20 +79,20 @@ Nested relations of those kind need to be persisted manually. **Arguments**: -- `relation_field (Optional[ForeignKeyField])`: field with relation leading to this model -- `previous_model (Model)`: previous model from which method came -- `exclude (Union[Set, Dict])`: items to exclude during saving of relations -- `relation_map (Dict)`: map of relations to follow -- `save_all (bool)`: flag if all models should be saved or only not saved ones -- `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 +- `relation_field` (`Optional[ForeignKeyField]`): field with relation leading to this model +- `previous_model` (`Model`): previous model from which method came +- `exclude` (`Union[Set, Dict]`): items to exclude during saving of relations +- `relation_map` (`Dict`): map of relations to follow +- `save_all` (`bool`): flag if all models should be saved or only not saved ones +- `follow` (`bool`): flag to trigger deep save - +- `update_count` (`int`): internal parameter for recursive calls - **Returns**: -`(int)`: number of updated/saved models +`int`: number of updated/saved models #### update @@ -110,8 +110,8 @@ Sets model save status to True. **Arguments**: -- `_columns (List)`: list of columns to update, if None all are updated -- `kwargs (Any)`: list of fields to update as field=value pairs +- `_columns` (`List`): list of columns to update, if None all are updated +- `kwargs` (`Any`): list of fields to update as field=value pairs **Raises**: @@ -119,7 +119,7 @@ Sets model save status to True. **Returns**: -`(Model)`: updated Model +`Model`: updated Model #### delete @@ -140,7 +140,7 @@ or update and the Model will be saved in database again. **Returns**: -`(int)`: number of deleted rows (for some backends) +`int`: number of deleted rows (for some backends) #### load @@ -159,7 +159,7 @@ Does NOT refresh the related models fields if they were loaded before. **Returns**: -`(Model)`: reloaded Model +`Model`: reloaded Model #### load\_all @@ -185,11 +185,11 @@ Nested relations of those kind need to be loaded manually. **Arguments**: -- `order_by (Union[List, str])`: columns by which models should be sorted -- `exclude (Union[List, str, Set, Dict])`: related models to exclude -- `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 +- `order_by` (`Union[List, str]`): columns by which models should be sorted +- `exclude` (`Union[List, str, Set, Dict]`): related models to exclude +- `follow` (`bool`): flag to trigger deep save - **Raises**: @@ -197,5 +197,5 @@ with follow=True also related models of related models are saved **Returns**: -`(Model)`: reloaded Model +`Model`: reloaded Model diff --git a/docs/api/models/new-basemodel.md b/docs/api/models/new-basemodel.md index 4fb0dfd..30e64e3 100644 --- a/docs/api/models/new-basemodel.md +++ b/docs/api/models/new-basemodel.md @@ -53,8 +53,8 @@ that has not been updated or unknown field is passed **Arguments**: -- `args (Any)`: ignored args -- `kwargs (Any)`: keyword arguments - all fields values and some special params +- `args` (`Any`): ignored args +- `kwargs` (`Any`): keyword arguments - all fields values and some special params #### \_\_setattr\_\_ @@ -63,71 +63,49 @@ that has not been updated or unknown field is passed | __setattr__(name: str, value: Any) -> None ``` -Overwrites setattr in object to allow for special behaviour of certain params. - -Parameter "pk" is translated into actual primary key field name. - -Relations are expanded (child model constructed if needed) and registered on -both ends of the relation. The related models are handled by RelationshipManager -exposed at _orm param. - -Json fields converted if needed. - -Setting pk, foreign key value or any other field value sets Model save status -to False. Setting a reverse relation or many to many relation does not as it -does not modify the state of the model (but related model or through model). - -To short circuit all checks and expansions the set of attribute names present -on each model is gathered into _quick_access_fields that is looked first and -if field is in this set the object setattr is called directly. +Overwrites setattr in pydantic parent as otherwise descriptors are not called. **Arguments**: -- `name (str)`: name of the attribute to set -- `value (Any)`: value of the attribute to set +- `name` (`str`): name of the attribute to set +- `value` (`Any`): value of the attribute to set **Returns**: -`(None)`: None +`None`: None - -#### \_\_getattribute\_\_ + +#### \_\_getattr\_\_ ```python - | __getattribute__(item: str) -> Any + | __getattr__(item: str) -> Any ``` -Because we need to overwrite getting the attribute by ormar instead of pydantic -as well as returning related models and not the value stored on the model the -__getattribute__ needs to be used not __getattr__. - -It's used to access all attributes so it can be a big overhead that's why a -number of short circuits is used. - -To short circuit all checks and expansions the set of attribute names present -on each model is gathered into _quick_access_fields that is looked first and -if field is in this set the object setattr is called directly. - -To avoid recursion object's getattribute is used to actually get the attribute -value from the model after the checks. - -Even the function calls are constructed with objects functions. - -Parameter "pk" is translated into actual primary key field name. - -Relations are returned so the actual related model is returned and not current -model's field. The related models are handled by RelationshipManager exposed -at _orm param. - -Json fields are converted if needed. +Used only to silence mypy errors for Through models and reverse relations. +Not used in real life as in practice calls are intercepted +by RelationDescriptors **Arguments**: -- `item (str)`: name of the attribute to retrieve +- `item` (`str`): name of attribute **Returns**: -`(Any)`: value of the attribute +`Any`: Any + + +#### \_internal\_set + +```python + | _internal_set(name: str, value: Any) -> None +``` + +Delegates call to pydantic. + +**Arguments**: + +- `name` (`str`): name of param +- `value` (`Any`): value to set #### \_verify\_model\_can\_be\_initialized @@ -140,24 +118,45 @@ Raises exception if model is abstract or has ForwardRefs in relation fields. **Returns**: -`(None)`: None +`None`: None - -#### \_extract\_related\_model\_instead\_of\_field + +#### \_process\_kwargs ```python - | _extract_related_model_instead_of_field(item: str) -> Optional[Union["Model", Sequence["Model"]]] + | _process_kwargs(kwargs: Dict) -> Tuple[Dict, Dict] ``` -Retrieves the related model/models from RelationshipManager. +Initializes nested models. + +Removes property_fields + +Checks if field is in the model fields or pydatnic fields. + +Nullifies fields that should be excluded. + +Extracts through models from kwargs into temporary dict. **Arguments**: -- `item (str)`: name of the relation +- `kwargs` (`Dict`): passed to init keyword arguments **Returns**: -`(Optional[Union[Model, List[Model]]])`: related model, list of related models or None +`Tuple[Dict, Dict]`: modified kwargs + + +#### \_initialize\_internal\_attributes + +```python + | _initialize_internal_attributes() -> None +``` + +Initializes internal attributes during __init__() + +**Returns**: + +`None`: #### \_\_eq\_\_ @@ -170,11 +169,11 @@ Compares other model to this model. when == is called. **Arguments**: -- `other (object)`: other model to compare +- `other` (`object`): other model to compare **Returns**: -`(bool)`: result of comparison +`bool`: result of comparison #### \_\_same\_\_ @@ -191,11 +190,11 @@ Compares: **Arguments**: -- `other (NewBaseModel)`: model to compare to +- `other` (`NewBaseModel`): model to compare to **Returns**: -`(bool)`: result of comparison +`bool`: result of comparison #### get\_name @@ -209,11 +208,11 @@ Returns name of the Model class, by default lowercase. **Arguments**: -- `lower (bool)`: flag if name should be set to lowercase +- `lower` (`bool`): flag if name should be set to lowercase **Returns**: -`(str)`: name of the model +`str`: name of the model #### pk\_column @@ -229,7 +228,7 @@ Only one primary key column is allowed. **Returns**: -`(sqlalchemy.Column)`: primary key sqlalchemy column +`sqlalchemy.Column`: primary key sqlalchemy column #### saved @@ -306,12 +305,12 @@ present in fastapi responses. **Arguments**: -- `include (Union[Set, Dict, None])`: fields to include -- `exclude (Union[Set, Dict, None])`: fields to exclude +- `include` (`Union[Set, Dict, None]`): fields to include +- `exclude` (`Union[Set, Dict, None]`): fields to exclude **Returns**: -`(Set[str])`: set of property fields names +`Set[str]`: set of property fields names #### update\_forward\_refs @@ -335,55 +334,57 @@ Calls the pydantic method to evaluate pydantic fields. **Arguments**: -- `localns (Any)`: local namespace +- `localns` (`Any`): local namespace **Returns**: -`(None)`: None +`None`: None -#### \_get\_related\_not\_excluded\_fields +#### \_get\_not\_excluded\_fields ```python - | _get_not_excluded_fields(include: Optional[Dict], exclude: Optional[Dict]) -> List + | @staticmethod + | _get_not_excluded_fields(fields: Union[List, Set], include: Optional[Dict], exclude: Optional[Dict]) -> List ``` Returns related field names applying on them include and exclude set. **Arguments**: -- `include (Union[Set, Dict, None])`: fields to include -- `exclude (Union[Set, Dict, None])`: fields to exclude +- `include` (`Union[Set, Dict, None]`): fields to include +- `exclude` (`Union[Set, Dict, None]`): fields to exclude **Returns**: -`(List of fields with relations that is not excluded)`: +`List of fields with relations that is not excluded`: #### \_extract\_nested\_models\_from\_list ```python | @staticmethod - | _extract_nested_models_from_list(relation_map: Dict, models: MutableSequence, include: Union[Set, Dict, None], exclude: Union[Set, Dict, None]) -> List + | _extract_nested_models_from_list(relation_map: Dict, models: MutableSequence, include: Union[Set, Dict, None], exclude: Union[Set, Dict, None], exclude_primary_keys: bool, exclude_through_models: bool) -> List ``` Converts list of models into list of dictionaries. **Arguments**: -- `models (List)`: List of models -- `include (Union[Set, Dict, None])`: fields to include -- `exclude (Union[Set, Dict, None])`: fields to exclude +- `models` (`List`): List of models +- `include` (`Union[Set, Dict, None]`): fields to include +- `exclude` (`Union[Set, Dict, None]`): fields to exclude **Returns**: -`(List[Dict])`: list of models converted to dictionaries +`List[Dict]`: list of models converted to dictionaries #### \_skip\_ellipsis ```python - | _skip_ellipsis(items: Union[Set, Dict, None], key: str, default_return: Any = None) -> Union[Set, Dict, None] + | @classmethod + | _skip_ellipsis(cls, items: Union[Set, Dict, None], key: str, default_return: Any = None) -> Union[Set, Dict, None] ``` Helper to traverse the include/exclude dictionaries. @@ -392,17 +393,18 @@ and not the actual set/dict with fields names. **Arguments**: -- `items (Union[Set, Dict, None])`: current include/exclude value -- `key (str)`: key for nested relations to check +- `items` (`Union[Set, Dict, None]`): current include/exclude value +- `key` (`str`): key for nested relations to check **Returns**: -`(Union[Set, Dict, None])`: nested value of the items +`Union[Set, Dict, None]`: nested value of the items #### \_convert\_all ```python + | @staticmethod | _convert_all(items: Union[Set, Dict, None]) -> Union[Set, Dict, None] ``` @@ -411,13 +413,13 @@ support index based exclusions. **Arguments**: -- `items (Union[Set, Dict, None])`: current include/exclude value +- `items` (`Union[Set, Dict, None]`): current include/exclude value #### \_extract\_nested\_models ```python - | _extract_nested_models(relation_map: Dict, dict_instance: Dict, include: Optional[Dict], exclude: Optional[Dict]) -> Dict + | _extract_nested_models(relation_map: Dict, dict_instance: Dict, include: Optional[Dict], exclude: Optional[Dict], exclude_primary_keys: bool, exclude_through_models: bool) -> Dict ``` Traverse nested models and converts them into dictionaries. @@ -425,20 +427,20 @@ Calls itself recursively if needed. **Arguments**: -- `nested (bool)`: flag if current instance is nested -- `dict_instance (Dict)`: current instance dict -- `include (Optional[Dict])`: fields to include -- `exclude (Optional[Dict])`: fields to exclude +- `nested` (`bool`): flag if current instance is nested +- `dict_instance` (`Dict`): current instance dict +- `include` (`Optional[Dict]`): fields to include +- `exclude` (`Optional[Dict]`): fields to exclude **Returns**: -`(Dict)`: current model dict with child models converted to dictionaries +`Dict`: current model dict with child models converted to dictionaries #### dict ```python - | dict(*, include: Union[Set, Dict] = None, exclude: Union[Set, Dict] = None, by_alias: bool = False, skip_defaults: bool = None, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, relation_map: Dict = None) -> "DictStrAny" + | dict(*, include: Union[Set, Dict] = None, exclude: Union[Set, Dict] = None, by_alias: bool = False, skip_defaults: bool = None, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, exclude_primary_keys: bool = False, exclude_through_models: bool = False, relation_map: Dict = None) -> "DictStrAny" ``` Generate a dictionary representation of the model, @@ -450,18 +452,33 @@ Additionally fields decorated with @property_field are also added. **Arguments**: -- `include (Union[Set, Dict, None])`: fields to include -- `exclude (Union[Set, Dict, None])`: fields to exclude -- `by_alias (bool)`: flag to get values by alias - passed to pydantic -- `skip_defaults (bool)`: flag to not set values - passed to pydantic -- `exclude_unset (bool)`: flag to exclude not set values - passed to pydantic -- `exclude_defaults (bool)`: flag to exclude default values - passed to pydantic -- `exclude_none (bool)`: flag to exclude None values - passed to pydantic -- `relation_map (Dict)`: map of the relations to follow to avoid circural deps +- `exclude_through_models` (`bool`): flag to exclude through models from dict +- `exclude_primary_keys` (`bool`): flag to exclude primary keys from dict +- `include` (`Union[Set, Dict, None]`): fields to include +- `exclude` (`Union[Set, Dict, None]`): fields to exclude +- `by_alias` (`bool`): flag to get values by alias - passed to pydantic +- `skip_defaults` (`bool`): flag to not set values - passed to pydantic +- `exclude_unset` (`bool`): flag to exclude not set values - passed to pydantic +- `exclude_defaults` (`bool`): flag to exclude default values - passed to pydantic +- `exclude_none` (`bool`): flag to exclude None values - passed to pydantic +- `relation_map` (`Dict`): map of the relations to follow to avoid circural deps **Returns**: -`()`: + + + +#### json + +```python + | json(*, include: Union[Set, Dict] = None, exclude: Union[Set, Dict] = None, by_alias: bool = False, skip_defaults: bool = None, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, encoder: Optional[Callable[[Any], Any]] = None, exclude_primary_keys: bool = False, exclude_through_models: bool = False, **dumps_kwargs: Any, ,) -> str +``` + +Generate a JSON representation of the model, `include` and `exclude` +arguments as per `dict()`. + +`encoder` is an optional function to supply as `default` to json.dumps(), +other arguments as per `json.dumps()`. #### update\_from\_dict @@ -474,47 +491,65 @@ Updates self with values of fields passed in the dictionary. **Arguments**: -- `value_dict (Dict)`: dictionary of fields names and values +- `value_dict` (`Dict`): dictionary of fields names and values **Returns**: -`(NewBaseModel)`: self +`NewBaseModel`: self + + +#### \_convert\_to\_bytes + +```python + | _convert_to_bytes(column_name: str, value: Any) -> Union[str, Dict] +``` + +Converts value to bytes from string + +**Arguments**: + +- `column_name` (`str`): name of the field +- `value` (`Any`): value fo the field + +**Returns**: + +`Any`: converted value if needed, else original value + + +#### \_convert\_bytes\_to\_str + +```python + | _convert_bytes_to_str(column_name: str, value: Any) -> Union[str, Dict] +``` + +Converts value to str from bytes for represent_as_base64_str columns. + +**Arguments**: + +- `column_name` (`str`): name of the field +- `value` (`Any`): value fo the field + +**Returns**: + +`Any`: converted value if needed, else original value #### \_convert\_json ```python - | _convert_json(column_name: str, value: Any, op: str) -> Union[str, Dict] + | _convert_json(column_name: str, value: Any) -> Union[str, Dict] ``` Converts value to/from json if needed (for Json columns). **Arguments**: -- `column_name (str)`: name of the field -- `value (Any)`: value fo the field -- `op (str)`: operator on json +- `column_name` (`str`): name of the field +- `value` (`Any`): value fo the field **Returns**: -`(Any)`: converted value if needed, else original value - - -#### \_is\_conversion\_to\_json\_needed - -```python - | _is_conversion_to_json_needed(column_name: str) -> bool -``` - -Checks if given column name is related to JSON field. - -**Arguments**: - -- `column_name (str)`: name of the field - -**Returns**: - -`(bool)`: result of the check +`Any`: converted value if needed, else original value #### \_extract\_own\_model\_fields @@ -528,7 +563,7 @@ relations fields (ForeignKey, ManyToMany etc.) **Returns**: -`(Dict)`: dictionary of fields names and values. +`Dict`: dictionary of fields names and values. #### \_extract\_model\_db\_fields @@ -544,7 +579,7 @@ That includes own non-relational fields ang foreign key fields. **Returns**: -`(Dict)`: dictionary of fields names and values. +`Dict`: dictionary of fields names and values. #### get\_relation\_model\_id @@ -557,9 +592,9 @@ Returns an id of the relation side model to use in prefetch query. **Arguments**: -- `target_field ("BaseField")`: field with relation definition +- `target_field` (`"BaseField"`): field with relation definition **Returns**: -`(Optional[int])`: value of pk if set +`Optional[int]`: value of pk if set diff --git a/docs/api/models/traversible.md b/docs/api/models/traversible.md index f83c91f..f0a0abb 100644 --- a/docs/api/models/traversible.md +++ b/docs/api/models/traversible.md @@ -21,13 +21,13 @@ Adds new Node or returns the existing one **Arguments**: -- `node_class (ormar.models.metaclass.ModelMetaclass)`: Model in current node -- `relation_name (str)`: name of the current relation -- `parent_node (Optional[Node])`: parent node +- `node_class` (`ormar.models.metaclass.ModelMetaclass`): Model in current node +- `relation_name` (`str`): name of the current relation +- `parent_node` (`Optional[Node]`): parent node **Returns**: -`(Node)`: returns new or already existing node +`Node`: returns new or already existing node #### find @@ -40,13 +40,13 @@ Searches for existing node with given parameters **Arguments**: -- `node_class (ormar.models.metaclass.ModelMetaclass)`: Model in current node -- `relation_name (str)`: name of the current relation -- `parent_node (Optional[Node])`: parent node +- `node_class` (`ormar.models.metaclass.ModelMetaclass`): Model in current node +- `relation_name` (`str`): name of the current relation +- `parent_node` (`Optional[Node]`): parent node **Returns**: -`(Optional[Node])`: returns already existing node or None +`Optional[Node]`: returns already existing node or None ## Node Objects @@ -70,9 +70,9 @@ Relation was visited if one of the parent node had the same Model class **Arguments**: -- `relation_name (str)`: name of relation +- `relation_name` (`str`): name of relation **Returns**: -`(bool)`: result of the check +`bool`: result of the check diff --git a/docs/api/query-set/clause.md b/docs/api/query-set/clause.md index 0efe18b..e6766b8 100644 --- a/docs/api/query-set/clause.md +++ b/docs/api/query-set/clause.md @@ -23,13 +23,13 @@ complex relation prefixes if needed and nested groups also resolved. **Arguments**: -- `model_cls (Type["Model"])`: model from which the query is run -- `select_related (List[str])`: list of models to join -- `filter_clauses (List[FilterAction])`: list of filter conditions +- `model_cls` (`Type["Model"]`): model from which the query is run +- `select_related` (`List[str]`): list of models to join +- `filter_clauses` (`List[FilterAction]`): list of filter conditions **Returns**: -`(Tuple[List[FilterAction], List[str]])`: list of filter conditions and select_related list +`Tuple[List[FilterAction], List[str]]`: list of filter conditions and select_related list #### \_iter @@ -42,7 +42,7 @@ Iterates all actions in a tree **Returns**: -`(Generator)`: generator yielding from own actions and nested groups +`Generator`: generator yielding from own actions and nested groups #### \_get\_text\_clauses @@ -55,7 +55,7 @@ Helper to return list of text queries from actions and nested groups **Returns**: -`(List[sqlalchemy.sql.elements.TextClause])`: list of text queries from actions and nested groups +`List[sqlalchemy.sql.elements.TextClause]`: list of text queries from actions and nested groups #### get\_text\_clause @@ -72,7 +72,7 @@ Compiles the clause. **Returns**: -`(sqlalchemy.sql.elements.TextClause)`: complied and escaped clause +`sqlalchemy.sql.elements.TextClause`: complied and escaped clause #### or\_ @@ -85,12 +85,12 @@ Construct or filter from nested groups and keyword arguments **Arguments**: -- `args (Tuple[FilterGroup])`: nested filter groups -- `kwargs (Any)`: fields names and proper value types +- `args` (`Tuple[FilterGroup]`): nested filter groups +- `kwargs` (`Any`): fields names and proper value types **Returns**: -`(ormar.queryset.clause.FilterGroup)`: FilterGroup ready to be resolved +`ormar.queryset.clause.FilterGroup`: FilterGroup ready to be resolved #### and\_ @@ -103,12 +103,12 @@ Construct and filter from nested groups and keyword arguments **Arguments**: -- `args (Tuple[FilterGroup])`: nested filter groups -- `kwargs (Any)`: fields names and proper value types +- `args` (`Tuple[FilterGroup]`): nested filter groups +- `kwargs` (`Any`): fields names and proper value types **Returns**: -`(ormar.queryset.clause.FilterGroup)`: FilterGroup ready to be resolved +`ormar.queryset.clause.FilterGroup`: FilterGroup ready to be resolved ## QueryClause Objects @@ -132,12 +132,12 @@ mentioned in select_related strings but not included in select_related. **Arguments**: -- `_own_only ()`: -- `kwargs (Any)`: key, value pair with column names and values +- `_own_only`: +- `kwargs` (`Any`): key, value pair with column names and values **Returns**: -`(Tuple[List[sqlalchemy.sql.elements.TextClause], List[str]])`: Tuple with list of where clauses and updated select_related list +`Tuple[List[sqlalchemy.sql.elements.TextClause], List[str]]`: Tuple with list of where clauses and updated select_related list #### \_populate\_filter\_clauses @@ -152,11 +152,11 @@ is determined and the final clause is escaped if needed and compiled. **Arguments**: -- `kwargs (Any)`: key, value pair with column names and values +- `kwargs` (`Any`): key, value pair with column names and values **Returns**: -`(Tuple[List[sqlalchemy.sql.elements.TextClause], List[str]])`: Tuple with list of where clauses and updated select_related list +`Tuple[List[sqlalchemy.sql.elements.TextClause], List[str]]`: Tuple with list of where clauses and updated select_related list #### \_register\_complex\_duplicates @@ -173,11 +173,11 @@ model and whole relation key (not just last relation name). **Arguments**: -- `select_related (List[str])`: list of relation strings +- `select_related` (`List[str]`): list of relation strings **Returns**: -`(None)`: None +`None`: None #### \_parse\_related\_prefixes @@ -190,11 +190,11 @@ Walks all relation strings and parses the target models and prefixes. **Arguments**: -- `select_related (List[str])`: list of relation strings +- `select_related` (`List[str]`): list of relation strings **Returns**: -`(List[Prefix])`: list of parsed prefixes +`List[Prefix]`: list of parsed prefixes #### \_switch\_filter\_action\_prefixes @@ -208,11 +208,11 @@ present in alias_manager. **Arguments**: -- `filter_clauses (List[FilterAction])`: raw list of actions +- `filter_clauses` (`List[FilterAction]`): raw list of actions **Returns**: -`(List[FilterAction])`: list of actions with aliases changed if needed +`List[FilterAction]`: list of actions with aliases changed if needed #### \_verify\_prefix\_and\_switch @@ -225,5 +225,5 @@ Helper to switch prefix to complex relation one if required **Arguments**: -- `action (ormar.queryset.actions.filter_action.FilterAction)`: action to switch prefix in +- `action` (`ormar.queryset.actions.filter_action.FilterAction`): action to switch prefix in diff --git a/docs/api/query-set/field-accessor.md b/docs/api/query-set/field-accessor.md index 8ef5e14..083fdd0 100644 --- a/docs/api/query-set/field-accessor.md +++ b/docs/api/query-set/field-accessor.md @@ -22,7 +22,7 @@ Hack to avoid pydantic name check from parent model, returns false **Returns**: -`(bool)`: False +`bool`: False #### \_\_getattr\_\_ @@ -36,11 +36,11 @@ Thanks to that operator overload is possible to use in filter. **Arguments**: -- `item (str)`: attribute name +- `item` (`str`): attribute name **Returns**: -`(ormar.queryset.field_accessor.FieldAccessor)`: FieldAccessor for field or nested model +`ormar.queryset.field_accessor.FieldAccessor`: FieldAccessor for field or nested model #### \_\_eq\_\_ @@ -53,11 +53,11 @@ overloaded to work as sql `column = ` **Arguments**: -- `other (str)`: value to check agains operator +- `other` (`str`): value to check agains operator **Returns**: -`(ormar.queryset.clause.FilterGroup)`: FilterGroup for operator +`ormar.queryset.clause.FilterGroup`: FilterGroup for operator #### \_\_ge\_\_ @@ -70,11 +70,11 @@ overloaded to work as sql `column >= ` **Arguments**: -- `other (str)`: value to check agains operator +- `other` (`str`): value to check agains operator **Returns**: -`(ormar.queryset.clause.FilterGroup)`: FilterGroup for operator +`ormar.queryset.clause.FilterGroup`: FilterGroup for operator #### \_\_gt\_\_ @@ -87,11 +87,11 @@ overloaded to work as sql `column > ` **Arguments**: -- `other (str)`: value to check agains operator +- `other` (`str`): value to check agains operator **Returns**: -`(ormar.queryset.clause.FilterGroup)`: FilterGroup for operator +`ormar.queryset.clause.FilterGroup`: FilterGroup for operator #### \_\_le\_\_ @@ -104,11 +104,11 @@ overloaded to work as sql `column <= ` **Arguments**: -- `other (str)`: value to check agains operator +- `other` (`str`): value to check agains operator **Returns**: -`(ormar.queryset.clause.FilterGroup)`: FilterGroup for operator +`ormar.queryset.clause.FilterGroup`: FilterGroup for operator #### \_\_lt\_\_ @@ -121,11 +121,11 @@ overloaded to work as sql `column < ` **Arguments**: -- `other (str)`: value to check agains operator +- `other` (`str`): value to check agains operator **Returns**: -`(ormar.queryset.clause.FilterGroup)`: FilterGroup for operator +`ormar.queryset.clause.FilterGroup`: FilterGroup for operator #### \_\_mod\_\_ @@ -138,11 +138,11 @@ overloaded to work as sql `column LIKE '%%'` **Arguments**: -- `other (str)`: value to check agains operator +- `other` (`str`): value to check agains operator **Returns**: -`(ormar.queryset.clause.FilterGroup)`: FilterGroup for operator +`ormar.queryset.clause.FilterGroup`: FilterGroup for operator #### \_\_lshift\_\_ @@ -155,11 +155,11 @@ overloaded to work as sql `column IN (, ,...)` **Arguments**: -- `other (str)`: value to check agains operator +- `other` (`str`): value to check agains operator **Returns**: -`(ormar.queryset.clause.FilterGroup)`: FilterGroup for operator +`ormar.queryset.clause.FilterGroup`: FilterGroup for operator #### \_\_rshift\_\_ @@ -172,11 +172,11 @@ overloaded to work as sql `column IS NULL` **Arguments**: -- `other (str)`: value to check agains operator +- `other` (`str`): value to check agains operator **Returns**: -`(ormar.queryset.clause.FilterGroup)`: FilterGroup for operator +`ormar.queryset.clause.FilterGroup`: FilterGroup for operator #### in\_ @@ -189,11 +189,11 @@ works as sql `column IN (, ,...)` **Arguments**: -- `other (str)`: value to check agains operator +- `other` (`str`): value to check agains operator **Returns**: -`(ormar.queryset.clause.FilterGroup)`: FilterGroup for operator +`ormar.queryset.clause.FilterGroup`: FilterGroup for operator #### iexact @@ -206,11 +206,11 @@ works as sql `column = ` case-insensitive **Arguments**: -- `other (str)`: value to check agains operator +- `other` (`str`): value to check agains operator **Returns**: -`(ormar.queryset.clause.FilterGroup)`: FilterGroup for operator +`ormar.queryset.clause.FilterGroup`: FilterGroup for operator #### contains @@ -223,11 +223,11 @@ works as sql `column LIKE '%%'` **Arguments**: -- `other (str)`: value to check agains operator +- `other` (`str`): value to check agains operator **Returns**: -`(ormar.queryset.clause.FilterGroup)`: FilterGroup for operator +`ormar.queryset.clause.FilterGroup`: FilterGroup for operator #### icontains @@ -240,11 +240,11 @@ works as sql `column LIKE '%%'` case-insensitive **Arguments**: -- `other (str)`: value to check agains operator +- `other` (`str`): value to check agains operator **Returns**: -`(ormar.queryset.clause.FilterGroup)`: FilterGroup for operator +`ormar.queryset.clause.FilterGroup`: FilterGroup for operator #### startswith @@ -257,11 +257,11 @@ works as sql `column LIKE '%'` **Arguments**: -- `other (str)`: value to check agains operator +- `other` (`str`): value to check agains operator **Returns**: -`(ormar.queryset.clause.FilterGroup)`: FilterGroup for operator +`ormar.queryset.clause.FilterGroup`: FilterGroup for operator #### istartswith @@ -274,11 +274,11 @@ works as sql `column LIKE '%'` case-insensitive **Arguments**: -- `other (str)`: value to check agains operator +- `other` (`str`): value to check agains operator **Returns**: -`(ormar.queryset.clause.FilterGroup)`: FilterGroup for operator +`ormar.queryset.clause.FilterGroup`: FilterGroup for operator #### endswith @@ -291,11 +291,11 @@ works as sql `column LIKE '%'` **Arguments**: -- `other (str)`: value to check agains operator +- `other` (`str`): value to check agains operator **Returns**: -`(ormar.queryset.clause.FilterGroup)`: FilterGroup for operator +`ormar.queryset.clause.FilterGroup`: FilterGroup for operator #### iendswith @@ -308,11 +308,11 @@ works as sql `column LIKE '%'` case-insensitive **Arguments**: -- `other (str)`: value to check agains operator +- `other` (`str`): value to check agains operator **Returns**: -`(ormar.queryset.clause.FilterGroup)`: FilterGroup for operator +`ormar.queryset.clause.FilterGroup`: FilterGroup for operator #### isnull @@ -325,11 +325,11 @@ works as sql `column IS NULL` or `IS NOT NULL` **Arguments**: -- `other (str)`: value to check agains operator +- `other` (`str`): value to check agains operator **Returns**: -`(ormar.queryset.clause.FilterGroup)`: FilterGroup for operator +`ormar.queryset.clause.FilterGroup`: FilterGroup for operator #### asc @@ -342,7 +342,7 @@ works as sql `column asc` **Returns**: -`(ormar.queryset.actions.OrderGroup)`: OrderGroup for operator +`ormar.queryset.actions.OrderGroup`: OrderGroup for operator #### desc @@ -355,5 +355,5 @@ works as sql `column desc` **Returns**: -`(ormar.queryset.actions.OrderGroup)`: OrderGroup for operator +`ormar.queryset.actions.OrderGroup`: OrderGroup for operator diff --git a/docs/api/query-set/filter-query.md b/docs/api/query-set/filter-query.md index fc81f6c..2520d74 100644 --- a/docs/api/query-set/filter-query.md +++ b/docs/api/query-set/filter-query.md @@ -21,9 +21,9 @@ Applies all filter clauses if set. **Arguments**: -- `expr (sqlalchemy.sql.selectable.Select)`: query to modify +- `expr` (`sqlalchemy.sql.selectable.Select`): query to modify **Returns**: -`(sqlalchemy.sql.selectable.Select)`: modified query +`sqlalchemy.sql.selectable.Select`: modified query diff --git a/docs/api/query-set/join.md b/docs/api/query-set/join.md index d6e7ce4..9d76444 100644 --- a/docs/api/query-set/join.md +++ b/docs/api/query-set/join.md @@ -20,7 +20,7 @@ Shortcut for ormar's model AliasManager stored on Meta. **Returns**: -`(AliasManager)`: alias manager from model's Meta +`AliasManager`: alias manager from model's Meta #### to\_table @@ -34,7 +34,7 @@ Shortcut to table name of the next model **Returns**: -`(str)`: name of the target table +`str`: name of the target table #### \_on\_clause @@ -48,13 +48,13 @@ into one text clause used in joins. **Arguments**: -- `previous_alias (str)`: alias of previous table -- `from_clause (str)`: from table name -- `to_clause (str)`: to table name +- `previous_alias` (`str`): alias of previous table +- `from_clause` (`str`): from table name +- `to_clause` (`str`): to table name **Returns**: -`(sqlalchemy.text)`: clause combining all strings +`sqlalchemy.text`: clause combining all strings #### build\_join @@ -70,7 +70,7 @@ used_aliases and sort_orders. **Returns**: -`(Tuple[List[str], Join, List[TextClause], collections.OrderedDict])`: list of used aliases, select from, list of aliased columns, sort orders +`Tuple[List[str], Join, List[TextClause], collections.OrderedDict]`: list of used aliases, select from, list of aliased columns, sort orders #### \_forward\_join @@ -110,8 +110,8 @@ Updated are: **Arguments**: -- `related_name (str)`: name of the relation to follow -- `remainder (Any)`: deeper tables if there are more nested joins +- `related_name` (`str`): name of the relation to follow +- `remainder` (`Any`): deeper tables if there are more nested joins #### \_process\_m2m\_through\_table @@ -147,11 +147,11 @@ Changes the same names in order_by queries if they are present. **Arguments**: -- `reverse (bool)`: flag if it's on_clause lookup - use reverse fields +- `reverse` (`bool`): flag if it's on_clause lookup - use reverse fields **Returns**: -`(str)`: new relation name switched to through model field +`str`: new relation name switched to through model field #### \_process\_join @@ -183,7 +183,7 @@ Verifies if proper field string is used. **Arguments**: -- `order_by (str)`: string with order by definition +- `order_by` (`str`): string with order by definition #### \_get\_alias\_and\_model @@ -196,11 +196,11 @@ Returns proper model and alias to be applied in the clause. **Arguments**: -- `order_by (str)`: string with order by definition +- `order_by` (`str`): string with order by definition **Returns**: -`(Tuple[str, Type["Model"]])`: alias and model to be used in clause +`Tuple[str, Type["Model"]]`: alias and model to be used in clause #### \_get\_order\_bys @@ -225,5 +225,5 @@ different for ManyToMany relation, ForeignKey and reverse related of relations. **Returns**: -`(Tuple[str, str])`: to key and from key +`Tuple[str, str]`: to key and from key diff --git a/docs/api/query-set/limit-query.md b/docs/api/query-set/limit-query.md index f505194..9cb357d 100644 --- a/docs/api/query-set/limit-query.md +++ b/docs/api/query-set/limit-query.md @@ -21,9 +21,9 @@ Applies the limit clause. **Arguments**: -- `expr (sqlalchemy.sql.selectable.Select)`: query to modify +- `expr` (`sqlalchemy.sql.selectable.Select`): query to modify **Returns**: -`(sqlalchemy.sql.selectable.Select)`: modified query +`sqlalchemy.sql.selectable.Select`: modified query diff --git a/docs/api/query-set/offset-query.md b/docs/api/query-set/offset-query.md index 90a0db2..60bef02 100644 --- a/docs/api/query-set/offset-query.md +++ b/docs/api/query-set/offset-query.md @@ -21,9 +21,9 @@ Applies the offset clause. **Arguments**: -- `expr (sqlalchemy.sql.selectable.Select)`: query to modify +- `expr` (`sqlalchemy.sql.selectable.Select`): query to modify **Returns**: -`(sqlalchemy.sql.selectable.Select)`: modified query +`sqlalchemy.sql.selectable.Select`: modified query diff --git a/docs/api/query-set/order-query.md b/docs/api/query-set/order-query.md index abe79e4..5a5c156 100644 --- a/docs/api/query-set/order-query.md +++ b/docs/api/query-set/order-query.md @@ -21,9 +21,9 @@ Applies all order_by clauses if set. **Arguments**: -- `expr (sqlalchemy.sql.selectable.Select)`: query to modify +- `expr` (`sqlalchemy.sql.selectable.Select`): query to modify **Returns**: -`(sqlalchemy.sql.selectable.Select)`: modified query +`sqlalchemy.sql.selectable.Select`: modified query diff --git a/docs/api/query-set/prefetch-query.md b/docs/api/query-set/prefetch-query.md index 0ab7ce2..06f42a7 100644 --- a/docs/api/query-set/prefetch-query.md +++ b/docs/api/query-set/prefetch-query.md @@ -14,12 +14,12 @@ order_by parameters was set. **Arguments**: -- `models (List[tests.test_prefetch_related.Division])`: list of models already fetched from db -- `orders_by (Dict[str, str])`: order by dictionary +- `models` (`List[tests.test_prefetch_related.Division]`): list of models already fetched from db +- `orders_by` (`Dict[str, str]`): order by dictionary **Returns**: -`(List[tests.test_prefetch_related.Division])`: sorted list of models +`List[tests.test_prefetch_related.Division]`: sorted list of models #### set\_children\_on\_model @@ -39,12 +39,12 @@ Also relation is registered as each child is set as parent related field name va **Arguments**: -- `model (Model)`: parent model instance -- `related (str)`: name of the related field -- `children (Dict[int, set])`: dictionary of children ids/ related field value -- `model_id (int)`: id of the model on which children should be set -- `models (Dict)`: dictionary of child models instances -- `orders_by (Dict)`: order_by dictionary +- `model` (`Model`): parent model instance +- `related` (`str`): name of the related field +- `children` (`Dict[int, set]`): dictionary of children ids/ related field value +- `model_id` (`int`): id of the model on which children should be set +- `models` (`Dict`): dictionary of child models instances +- `orders_by` (`Dict`): order_by dictionary ## PrefetchQuery Objects @@ -74,12 +74,12 @@ Returns list with related models already prefetched and set. **Arguments**: -- `models (List[Model])`: list of already instantiated models from main query -- `rows (List[sqlalchemy.engine.result.RowProxy])`: row sql result of the main query before the prefetch +- `models` (`List[Model]`): list of already instantiated models from main query +- `rows` (`List[sqlalchemy.engine.result.RowProxy]`): row sql result of the main query before the prefetch **Returns**: -`(List[Model])`: list of models with children prefetched +`List[Model]`: list of models with children prefetched #### \_extract\_ids\_from\_raw\_data @@ -93,12 +93,12 @@ prefixed column name. **Arguments**: -- `parent_model (Type[Model])`: ormar model class -- `column_name (str)`: name of the relation column which is a key column +- `parent_model` (`Type[Model]`): ormar model class +- `column_name` (`str`): name of the relation column which is a key column **Returns**: -`(set)`: set of ids of related model that should be extracted +`set`: set of ids of related model that should be extracted #### \_extract\_ids\_from\_preloaded\_models @@ -112,12 +112,12 @@ in the original query before. **Arguments**: -- `parent_model (Type["Model"])`: model from which related ids should be extracted -- `column_name (str)`: name of the relation column which is a key column +- `parent_model` (`Type["Model"]`): model from which related ids should be extracted +- `column_name` (`str`): name of the relation column which is a key column **Returns**: -`(set)`: set of ids of related model that should be extracted +`set`: set of ids of related model that should be extracted #### \_extract\_required\_ids @@ -131,13 +131,13 @@ or from already populated models. **Arguments**: -- `parent_model (Type["Model"])`: model from which related ids should be extracted -- `reverse (bool)`: flag if the relation is reverse -- `related (str)`: name of the field with relation +- `parent_model` (`Type["Model"]`): model from which related ids should be extracted +- `reverse` (`bool`): flag if the relation is reverse +- `related` (`str`): name of the field with relation **Returns**: -`(set)`: set of ids of related model that should be extracted +`set`: set of ids of related model that should be extracted #### \_get\_filter\_for\_prefetch @@ -153,14 +153,14 @@ If there are no ids for relation the empty list is returned. **Arguments**: -- `parent_model (Type["Model"])`: model from which related ids should be extracted -- `target_model (Type["Model"])`: model to which relation leads to -- `reverse (bool)`: flag if the relation is reverse -- `related (str)`: name of the field with relation +- `parent_model` (`Type["Model"]`): model from which related ids should be extracted +- `target_model` (`Type["Model"]`): model to which relation leads to +- `reverse` (`bool`): flag if the relation is reverse +- `related` (`str`): name of the field with relation **Returns**: -`(List[sqlalchemy.sql.elements.TextClause])`: +`List[sqlalchemy.sql.elements.TextClause]`: #### \_populate\_nested\_related @@ -174,13 +174,13 @@ included in prefetch query. **Arguments**: -- `model (Model)`: ormar model instance -- `prefetch_dict (Dict)`: dictionary of models to prefetch -- `orders_by (Dict)`: dictionary of order bys +- `model` (`Model`): ormar model instance +- `prefetch_dict` (`Dict`): dictionary of models to prefetch +- `orders_by` (`Dict`): dictionary of order bys **Returns**: -`(Model)`: model with children populated +`Model`: model with children populated #### \_prefetch\_related\_models @@ -201,12 +201,12 @@ on each of the parent models from list. **Arguments**: -- `models (List[Model])`: list of parent models from main query -- `rows (List[sqlalchemy.engine.result.RowProxy])`: raw response from sql query +- `models` (`List[Model]`): list of parent models from main query +- `rows` (`List[sqlalchemy.engine.result.RowProxy]`): raw response from sql query **Returns**: -`(List[Model])`: list of models with prefetch children populated +`List[Model]`: list of models with prefetch children populated #### \_extract\_related\_models @@ -225,17 +225,17 @@ Calls itself recurrently to extract deeper nested relations of related model. **Arguments**: -- `related (str)`: name of the relation -- `target_model (Type[Model])`: model to which relation leads to -- `prefetch_dict (Dict)`: prefetch related list converted into dictionary -- `select_dict (Dict)`: select related list converted into dictionary -- `fields (Union[Set[Any], Dict[Any, Any], None])`: fields to include -- `exclude_fields (Union[Set[Any], Dict[Any, Any], None])`: fields to exclude -- `orders_by (Dict)`: dictionary of order bys clauses +- `related` (`str`): name of the relation +- `target_model` (`Type[Model]`): model to which relation leads to +- `prefetch_dict` (`Dict`): prefetch related list converted into dictionary +- `select_dict` (`Dict`): select related list converted into dictionary +- `fields` (`Union[Set[Any], Dict[Any, Any], None]`): fields to include +- `exclude_fields` (`Union[Set[Any], Dict[Any, Any], None]`): fields to exclude +- `orders_by` (`Dict`): dictionary of order bys clauses **Returns**: -`(None)`: None +`None`: None #### \_run\_prefetch\_query @@ -252,12 +252,12 @@ models. **Arguments**: -- `target_field ("BaseField")`: ormar field with relation definition -- `filter_clauses (List[sqlalchemy.sql.elements.TextClause])`: list of clauses, actually one clause with ids of relation +- `target_field` (`"BaseField"`): ormar field with relation definition +- `filter_clauses` (`List[sqlalchemy.sql.elements.TextClause]`): list of clauses, actually one clause with ids of relation **Returns**: -`(Tuple[str, List])`: table prefix and raw rows from sql response +`Tuple[str, List]`: table prefix and raw rows from sql response #### \_get\_select\_related\_if\_apply @@ -272,12 +272,12 @@ deeper on related model and already loaded in select related query. **Arguments**: -- `related (str)`: name of the relation -- `select_dict (Dict)`: dictionary of select related models in main query +- `related` (`str`): name of the relation +- `select_dict` (`Dict`): dictionary of select related models in main query **Returns**: -`(Dict)`: dictionary with nested related of select related +`Dict`: dictionary with nested related of select related #### \_update\_already\_loaded\_rows @@ -290,9 +290,9 @@ Updates models that are already loaded, usually children of children. **Arguments**: -- `target_field ("BaseField")`: ormar field with relation definition -- `prefetch_dict (Dict)`: dictionaries of related models to prefetch -- `orders_by (Dict)`: dictionary of order by clauses by model +- `target_field` (`"BaseField"`): ormar field with relation definition +- `prefetch_dict` (`Dict`): dictionaries of related models to prefetch +- `orders_by` (`Dict`): dictionary of order by clauses by model #### \_populate\_rows @@ -312,11 +312,11 @@ and set on the parent model after sorting if needed. **Arguments**: -- `excludable (ExcludableItems)`: structure of fields to include and exclude -- `rows (List[sqlalchemy.engine.result.RowProxy])`: raw sql response from the prefetch query -- `target_field ("BaseField")`: field with relation definition from parent model -- `parent_model (Type[Model])`: model with relation definition -- `table_prefix (str)`: prefix of the target table from current relation -- `prefetch_dict (Dict)`: dictionaries of related models to prefetch -- `orders_by (Dict)`: dictionary of order by clauses by model +- `excludable` (`ExcludableItems`): structure of fields to include and exclude +- `rows` (`List[sqlalchemy.engine.result.RowProxy]`): raw sql response from the prefetch query +- `target_field` (`"BaseField"`): field with relation definition from parent model +- `parent_model` (`Type[Model]`): model with relation definition +- `table_prefix` (`str`): prefix of the target table from current relation +- `prefetch_dict` (`Dict`): dictionaries of related models to prefetch +- `orders_by` (`Dict`): dictionary of order by clauses by model diff --git a/docs/api/query-set/query-set.md b/docs/api/query-set/query-set.md index d259202..b7aa53e 100644 --- a/docs/api/query-set/query-set.md +++ b/docs/api/query-set/query-set.md @@ -22,7 +22,7 @@ Shortcut to model class Meta set on QuerySet model. **Returns**: -`(model Meta class)`: Meta class of the model +`model Meta class`: Meta class of the model #### model @@ -36,7 +36,7 @@ Shortcut to model class set on QuerySet. **Returns**: -`(Type[Model])`: model class +`Type[Model]`: model class #### rebuild\_self @@ -52,36 +52,36 @@ all not passed params are taken from current values. #### \_prefetch\_related\_models ```python - | async _prefetch_related_models(models: List[Optional["T"]], rows: List) -> List[Optional["T"]] + | async _prefetch_related_models(models: List["T"], rows: List) -> List["T"] ``` Performs prefetch query for selected models names. **Arguments**: -- `models (List[Model])`: list of already parsed main Models from main query -- `rows (List[sqlalchemy.engine.result.RowProxy])`: database rows from main query +- `models` (`List[Model]`): list of already parsed main Models from main query +- `rows` (`List[sqlalchemy.engine.result.RowProxy]`): database rows from main query **Returns**: -`(List[Model])`: list of models with prefetch models populated +`List[Model]`: list of models with prefetch models populated #### \_process\_query\_result\_rows ```python - | _process_query_result_rows(rows: List) -> List[Optional["T"]] + | _process_query_result_rows(rows: List) -> List["T"] ``` Process database rows and initialize ormar Model from each of the rows. **Arguments**: -- `rows (List[sqlalchemy.engine.result.RowProxy])`: list of database rows from query result +- `rows` (`List[sqlalchemy.engine.result.RowProxy]`): list of database rows from query result **Returns**: -`(List[Model])`: list of models +`List[Model]`: list of models #### \_resolve\_filter\_groups @@ -94,11 +94,11 @@ Resolves filter groups to populate FilterAction params in group tree. **Arguments**: -- `groups (Any)`: tuple of FilterGroups +- `groups` (`Any`): tuple of FilterGroups **Returns**: -`(Tuple[List[FilterGroup], List[str]])`: list of resolver groups +`Tuple[List[FilterGroup], List[str]]`: list of resolver groups #### check\_single\_result\_rows\_count @@ -112,7 +112,7 @@ Verifies if the result has one and only one row. **Arguments**: -- `rows (List[Model])`: one element list of Models +- `rows` (`List[Model]`): one element list of Models #### database @@ -126,7 +126,7 @@ Shortcut to models database from Meta class. **Returns**: -`(databases.Database)`: database +`databases.Database`: database #### table @@ -140,7 +140,7 @@ Shortcut to models table from Meta class. **Returns**: -`(sqlalchemy.Table)`: database table +`sqlalchemy.Table`: database table #### build\_select\_expression @@ -154,13 +154,13 @@ If any of the params is not passed the QuerySet own value is used. **Arguments**: -- `limit (int)`: number to limit the query -- `offset (int)`: number to offset by -- `order_bys (List)`: list of order-by fields names +- `limit` (`int`): number to limit the query +- `offset` (`int`): number to offset by +- `order_bys` (`List`): list of order-by fields names **Returns**: -`(sqlalchemy.sql.selectable.Select)`: built sqlalchemy select expression +`sqlalchemy.sql.selectable.Select`: built sqlalchemy select expression #### filter @@ -190,14 +190,16 @@ You can use special filter suffix to change the filter operands: * endswith - like `album__name__endswith='ibu'` (exact end match) * iendswith - like `album__name__iendswith='IBU'` (case insensitive) +Note that you can also use python style filters - check the docs! + **Arguments**: -- `_exclude (bool)`: flag if it should be exclude or filter -- `kwargs (Any)`: fields names and proper value types +- `_exclude` (`bool`): flag if it should be exclude or filter +- `kwargs` (`Any`): fields names and proper value types **Returns**: -`(QuerySet)`: filtered QuerySet +`QuerySet`: filtered QuerySet #### exclude @@ -220,11 +222,11 @@ becomes a union of conditions. **Arguments**: -- `kwargs (Any)`: fields names and proper value types +- `kwargs` (`Any`): fields names and proper value types **Returns**: -`(QuerySet)`: filtered QuerySet +`QuerySet`: filtered QuerySet #### select\_related @@ -245,11 +247,11 @@ To chain related `Models` relation use double underscores between names. **Arguments**: -- `related (Union[List, str])`: list of relation field names, can be linked by '__' to nest +- `related` (`Union[List, str]`): list of relation field names, can be linked by '__' to nest **Returns**: -`(QuerySet)`: QuerySet +`QuerySet`: QuerySet #### select\_all @@ -272,13 +274,13 @@ Nested relations of those kind need to be loaded manually. **Arguments**: -- `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 +- `follow` (`bool`): flag to trigger deep save - **Returns**: -`(Model)`: reloaded Model +`Model`: reloaded Model #### prefetch\_related @@ -300,11 +302,11 @@ To chain related `Models` relation use double underscores between names. **Arguments**: -- `related (Union[List, str])`: list of relation field names, can be linked by '__' to nest +- `related` (`Union[List, str]`): list of relation field names, can be linked by '__' to nest **Returns**: -`(QuerySet)`: QuerySet +`QuerySet`: QuerySet #### fields @@ -351,12 +353,12 @@ To include whole nested model specify model related field name and ellipsis. **Arguments**: -- `_is_exclude (bool)`: flag if it's exclude or include operation -- `columns (Union[List, str, Set, Dict])`: columns to include +- `_is_exclude` (`bool`): flag if it's exclude or include operation +- `columns` (`Union[List, str, Set, Dict]`): columns to include **Returns**: -`(QuerySet)`: QuerySet +`QuerySet`: QuerySet #### exclude\_fields @@ -387,11 +389,11 @@ if explicitly excluded. **Arguments**: -- `columns (Union[List, str, Set, Dict])`: columns to exclude +- `columns` (`Union[List, str, Set, Dict]`): columns to exclude **Returns**: -`(QuerySet)`: QuerySet +`QuerySet`: QuerySet #### order\_by @@ -427,11 +429,57 @@ To sort in descending order provide a hyphen in front of the field name **Arguments**: -- `columns (Union[List, str])`: columns by which models should be sorted +- `columns` (`Union[List, str]`): columns by which models should be sorted **Returns**: -`(QuerySet)`: QuerySet +`QuerySet`: QuerySet + + +#### values + +```python + | async values(fields: Union[List, str, Set, Dict] = None, exclude_through: bool = False, _as_dict: bool = True, _flatten: bool = False) -> List +``` + +Return a list of dictionaries with column values in order of the fields +passed or all fields from queried models. + +To filter for given row use filter/exclude methods before values, +to limit number of rows use limit/offset or paginate before values. + +Note that it always return a list even for one row from database. + +**Arguments**: + +- `exclude_through` (`bool`): flag if through models should be excluded +- `_flatten` (`bool`): internal parameter to flatten one element tuples +- `_as_dict` (`bool`): internal parameter if return dict or tuples +- `fields` (`Union[List, str, Set, Dict]`): field name or list of field names to extract from db + + +#### values\_list + +```python + | async values_list(fields: Union[List, str, Set, Dict] = None, flatten: bool = False, exclude_through: bool = False) -> List +``` + +Return a list of tuples with column values in order of the fields passed or +all fields from queried models. + +When one field is passed you can flatten the list of tuples into list of values +of that single field. + +To filter for given row use filter/exclude methods before values, +to limit number of rows use limit/offset or paginate before values. + +Note that it always return a list even for one row from database. + +**Arguments**: + +- `exclude_through` (`bool`): flag if through models should be excluded +- `fields` (`Union[str, List[str]]`): field name or list of field names to extract from db +- `flatten` (`bool`): when one field is passed you can flatten the list of tuples #### exists @@ -445,7 +493,7 @@ Returns a bool value to confirm if there are rows matching the given criteria **Returns**: -`(bool)`: result of the check +`bool`: result of the check #### count @@ -459,7 +507,7 @@ Returns number of rows matching the given criteria **Returns**: -`(int)`: number of rows +`int`: number of rows #### max @@ -473,7 +521,7 @@ Returns max value of columns for rows matching the given criteria **Returns**: -`(Any)`: max value of column(s) +`Any`: max value of column(s) #### min @@ -487,7 +535,7 @@ Returns min value of columns for rows matching the given criteria **Returns**: -`(Any)`: min value of column(s) +`Any`: min value of column(s) #### sum @@ -501,7 +549,7 @@ Returns sum value of columns for rows matching the given criteria **Returns**: -`(int)`: sum value of columns +`int`: sum value of columns #### avg @@ -515,7 +563,7 @@ Returns avg value of columns for rows matching the given criteria **Returns**: -`(Union[int, float, List])`: avg value of columns +`Union[int, float, List]`: avg value of columns #### update @@ -531,12 +579,12 @@ each=True flag to affect whole table. **Arguments**: -- `each (bool)`: flag if whole table should be affected if no filter is passed -- `kwargs (Any)`: fields names and proper value types +- `each` (`bool`): flag if whole table should be affected if no filter is passed +- `kwargs` (`Any`): fields names and proper value types **Returns**: -`(int)`: number of updated rows +`int`: number of updated rows #### delete @@ -552,12 +600,12 @@ each=True flag to affect whole table. **Arguments**: -- `each (bool)`: flag if whole table should be affected if no filter is passed -- `kwargs (Any)`: fields names and proper value types +- `each` (`bool`): flag if whole table should be affected if no filter is passed +- `kwargs` (`Any`): fields names and proper value types **Returns**: -`(int)`: number of deleted rows +`int`: number of deleted rows #### paginate @@ -571,12 +619,12 @@ Limit is set to page size and offset is set to (page-1) * page_size. **Arguments**: -- `page_size (int)`: numbers of items per page -- `page (int)`: page number +- `page_size` (`int`): numbers of items per page +- `page` (`int`): page number **Returns**: -`(QuerySet)`: QuerySet +`QuerySet`: QuerySet #### limit @@ -592,12 +640,12 @@ models use the `limit_raw_sql` parameter flag, and set it to `True`. **Arguments**: -- `limit_raw_sql (bool)`: flag if raw sql should be limited -- `limit_count (int)`: number of models to limit +- `limit_raw_sql` (`bool`): flag if raw sql should be limited +- `limit_count` (`int`): number of models to limit **Returns**: -`(QuerySet)`: QuerySet +`QuerySet`: QuerySet #### offset @@ -613,12 +661,12 @@ models use the `limit_raw_sql` parameter flag, and set it to `True`. **Arguments**: -- `limit_raw_sql (bool)`: flag if raw sql should be offset -- `offset (int)`: numbers of models to offset +- `limit_raw_sql` (`bool`): flag if raw sql should be offset +- `offset` (`int`): numbers of models to offset **Returns**: -`(QuerySet)`: QuerySet +`QuerySet`: QuerySet #### first @@ -636,11 +684,11 @@ Gets the first row from the db ordered by primary key column ascending. **Arguments**: -- `kwargs (Any)`: fields names and proper value types +- `kwargs` (`Any`): fields names and proper value types **Returns**: -`(Model)`: returned model +`Model`: returned model #### get\_or\_none @@ -653,17 +701,18 @@ Get's the first row from the db meeting the criteria set by kwargs. If no criteria set it will return the last row in db sorted by pk. -Passing a criteria is actually calling filter(**kwargs) method described below. +Passing a criteria is actually calling filter(*args, **kwargs) method described +below. If not match is found None will be returned. **Arguments**: -- `kwargs (Any)`: fields names and proper value types +- `kwargs` (`Any`): fields names and proper value types **Returns**: -`(Model)`: returned model +`Model`: returned model #### get @@ -676,7 +725,8 @@ Get's the first row from the db meeting the criteria set by kwargs. If no criteria set it will return the last row in db sorted by pk. -Passing a criteria is actually calling filter(**kwargs) method described below. +Passing a criteria is actually calling filter(*args, **kwargs) method described +below. **Raises**: @@ -685,11 +735,11 @@ Passing a criteria is actually calling filter(**kwargs) method described below. **Arguments**: -- `kwargs (Any)`: fields names and proper value types +- `kwargs` (`Any`): fields names and proper value types **Returns**: -`(Model)`: returned model +`Model`: returned model #### get\_or\_create @@ -700,17 +750,20 @@ Passing a criteria is actually calling filter(**kwargs) method described below. Combination of create and get methods. -Tries to get a row meeting the criteria fro kwargs +Tries to get a row meeting the criteria for kwargs and if `NoMatch` exception is raised it creates a new one with given kwargs. +Passing a criteria is actually calling filter(*args, **kwargs) method described +below. + **Arguments**: -- `kwargs (Any)`: fields names and proper value types +- `kwargs` (`Any`): fields names and proper value types **Returns**: -`(Model)`: returned or created Model +`Model`: returned or created Model #### update\_or\_create @@ -723,32 +776,33 @@ Updates the model, or in case there is no match in database creates a new one. **Arguments**: -- `kwargs (Any)`: fields names and proper value types +- `kwargs` (`Any`): fields names and proper value types **Returns**: -`(Model)`: updated or created model +`Model`: updated or created model #### all ```python - | async all(*args: Any, **kwargs: Any) -> List[Optional["T"]] + | async all(*args: Any, **kwargs: Any) -> List["T"] ``` Returns all rows from a database for given model for set filter options. -Passing kwargs is a shortcut and equals to calling `filter(**kwrags).all()`. +Passing args and/or kwargs is a shortcut and equals to calling +`filter(*args, **kwargs).all()`. If there are no rows meeting the criteria an empty list is returned. **Arguments**: -- `kwargs (Any)`: fields names and proper value types +- `kwargs` (`Any`): fields names and proper value types **Returns**: -`(List[Model])`: list of returned models +`List[Model]`: list of returned models #### create @@ -764,11 +818,11 @@ The allowed kwargs are `Model` fields names and proper value types. **Arguments**: -- `kwargs (Any)`: fields names and proper value types +- `kwargs` (`Any`): fields names and proper value types **Returns**: -`(Model)`: created model +`Model`: created model #### bulk\_create @@ -787,7 +841,7 @@ Bulk operations do not send signals. **Arguments**: -- `objects (List[Model])`: list of ormar models already initialized and ready to save. +- `objects` (`List[Model]`): list of ormar models already initialized and ready to save. #### bulk\_update @@ -809,6 +863,6 @@ Bulk operations do not send signals. **Arguments**: -- `objects (List[Model])`: list of ormar models -- `columns (List[str])`: list of columns to update +- `objects` (`List[Model]`): list of ormar models +- `columns` (`List[str]`): list of columns to update diff --git a/docs/api/query-set/query.md b/docs/api/query-set/query.md index fc086c9..6c990d0 100644 --- a/docs/api/query-set/query.md +++ b/docs/api/query-set/query.md @@ -51,7 +51,7 @@ at the end of whole query. **Returns**: -`(bool)`: result of the check +`bool`: result of the check #### build\_select\_expression @@ -70,7 +70,7 @@ Returns ready to run query with all joins and clauses. **Returns**: -`(sqlalchemy.sql.selectable.Select)`: ready to run query with all joins and clauses. +`sqlalchemy.sql.selectable.Select`: ready to run query with all joins and clauses. #### \_build\_pagination\_condition @@ -111,11 +111,11 @@ Returns complete ready to run query. **Arguments**: -- `expr (sqlalchemy.sql.selectable.Select)`: select expression before clauses +- `expr` (`sqlalchemy.sql.selectable.Select`): select expression before clauses **Returns**: -`(sqlalchemy.sql.selectable.Select)`: expresion with all present clauses applied +`sqlalchemy.sql.selectable.Select`: expresion with all present clauses applied #### \_reset\_query\_parameters diff --git a/docs/api/query-set/reverse-alias-resolver.md b/docs/api/query-set/reverse-alias-resolver.md new file mode 100644 index 0000000..2eca833 --- /dev/null +++ b/docs/api/query-set/reverse-alias-resolver.md @@ -0,0 +1,139 @@ + +# queryset.reverse\_alias\_resolver + + +## ReverseAliasResolver Objects + +```python +class ReverseAliasResolver() +``` + +Class is used to reverse resolve table aliases into relation strings +to parse raw data columns and replace table prefixes with full relation string + + +#### resolve\_columns + +```python + | resolve_columns(columns_names: List[str]) -> Dict +``` + +Takes raw query prefixed column and resolves the prefixes to +relation strings (relation names connected with dunders). + +**Arguments**: + +- `columns_names` (`List[str]`): list of column names with prefixes from query + +**Returns**: + +`Union[None, Dict[str, str]]`: dictionary of prefix: resolved names + + +#### \_resolve\_column\_with\_prefix + +```python + | _resolve_column_with_prefix(column_name: str, prefix: str) -> None +``` + +Takes the prefixed column, checks if field should be excluded, and if not +it proceeds to replace prefix of a table with full relation string. + +Sample: translates: "xsd12df_name" -> into: "posts__user__name" + +**Arguments**: + +- `column_name` (`str`): prefixed name of the column +- `prefix` (`str`): extracted prefix + + +#### \_check\_if\_field\_is\_excluded + +```python + | _check_if_field_is_excluded(prefix: str, field: "ForeignKeyField", is_through: bool) -> bool +``` + +Checks if given relation is excluded in current query. + +Note that in contrary to other queryset methods here you can exclude the +in-between models but keep the end columns, which does not make sense +when parsing the raw data into models. + +So in relation category -> category_x_post -> post -> user you can exclude +category_x_post and post models but can keep the user one. (in ormar model +context that is not possible as if you would exclude through and post model +there would be no way to reach user model). + +Exclusions happen on a model before the current one, so we need to move back +in chain of model by one or by two (m2m relations have through model in between) + +**Arguments**: + +- `prefix` (`str`): table alias +- `field` (`ForeignKeyField`): field with relation +- `is_through` (`bool`): flag if current table is a through table + +**Returns**: + +`bool`: result of the check + + +#### \_get\_previous\_excludable + +```python + | _get_previous_excludable(prefix: str, field: "ForeignKeyField", shift: int = 1) -> "Excludable" +``` + +Returns excludable related to model previous in chain of models. +Used to check if current model should be excluded. + +**Arguments**: + +- `prefix` (`str`): prefix of a current table +- `field` (`ForeignKeyField`): field with relation +- `shift` (`int`): how many model back to go - for m2m it's 2 due to through models + +**Returns**: + +`Excludable`: excludable for previous model + + +#### \_create\_prefixes\_map + +```python + | _create_prefixes_map() -> None +``` + +Creates a map of alias manager aliases keys to relation strings. +I.e in alias manager you can have alias user_roles: xas12ad + +This method will create entry user_roles: roles, where roles is a name of +relation on user model. + +Will also keep the relation field in separate dictionary so we can later +extract field names and owner models. + + +#### \_handle\_through\_fields\_and\_prefix + +```python + | _handle_through_fields_and_prefix(model_cls: Type["Model"], field: "ForeignKeyField", previous_related_str: str, relation: str) -> str +``` + +Registers through models for m2m relations and switches prefix for +the one linking from through model to target model. + +For other relations returns current model name + relation name as prefix. +Nested relations are a chain of relation names with __ in between. + +**Arguments**: + +- `model_cls` (`Type["Model"]`): model of current relation +- `field` (`ForeignKeyField`): field with relation +- `previous_related_str` (`str`): concatenated chain linked with "__" +- `relation` (`str`): name of the current relation in chain + +**Returns**: + +`str`: name of prefix to populate + diff --git a/docs/api/query-set/utils.md b/docs/api/query-set/utils.md index 2268086..42a30aa 100644 --- a/docs/api/query-set/utils.md +++ b/docs/api/query-set/utils.md @@ -16,13 +16,13 @@ All those checks verify if there is a need for deeper traversal. **Arguments**: -- `part (str)`: -- `parts (List[str])`: -- `current_level (Any)`: current level of the traversed structure +- `part` (`str`): +- `parts` (`List[str]`): +- `current_level` (`Any`): current level of the traversed structure **Returns**: -`(bool)`: result of the check +`bool`: result of the check #### translate\_list\_to\_dict @@ -39,13 +39,13 @@ Default required key ise Ellipsis like in pydantic. **Arguments**: -- `list_to_trans (set)`: input list -- `is_order (bool)`: flag if change affects order_by clauses are they require special default value with sort order. +- `list_to_trans` (`set`): input list +- `is_order` (`bool`): flag if change affects order_by clauses are they require special **Returns**: -`(Dict)`: converted to dictionary input list +`Dict`: converted to dictionary input list #### convert\_set\_to\_required\_dict @@ -59,11 +59,11 @@ Required key is Ellipsis. **Arguments**: -- `set_to_convert (set)`: set to convert to dict +- `set_to_convert` (`set`): set to convert to dict **Returns**: -`(Dict)`: set converted to dict of ellipsis +`Dict`: set converted to dict of ellipsis #### update @@ -79,12 +79,12 @@ only other values are overwritten. **Arguments**: -- `current_dict (Dict[str, ellipsis])`: dict to update -- `updating_dict (Dict)`: dict with values to update +- `current_dict` (`Dict[str, ellipsis]`): dict to update +- `updating_dict` (`Dict`): dict with values to update **Returns**: -`(Dict)`: combination of both dicts +`Dict`: combination of both dicts #### subtract\_dict @@ -100,12 +100,12 @@ only other values are overwritten. **Arguments**: -- `current_dict (Dict[str, ellipsis])`: dict to update -- `updating_dict (Dict)`: dict with values to update +- `current_dict` (`Dict[str, ellipsis]`): dict to update +- `updating_dict` (`Dict`): dict with values to update **Returns**: -`(Dict)`: combination of both dicts +`Dict`: combination of both dicts #### update\_dict\_from\_list @@ -119,12 +119,12 @@ nested keys that are sets or dicts are combined and not overwritten. **Arguments**: -- `curr_dict (Dict)`: dict to update -- `list_to_update (List[str])`: list with values to update the dict +- `curr_dict` (`Dict`): dict to update +- `list_to_update` (`List[str]`): list with values to update the dict **Returns**: -`(Dict)`: updated dict +`Dict`: updated dict #### extract\_nested\_models @@ -144,10 +144,10 @@ Goes also into nested relations if needed (specified in select_dict). **Arguments**: -- `model (Model)`: parent Model -- `model_type (Type[Model])`: parent model class -- `select_dict (Dict)`: dictionary of related models from select_related -- `extracted (Dict)`: dictionary with already extracted models +- `model` (`Model`): parent Model +- `model_type` (`Type[Model]`): parent model class +- `select_dict` (`Dict`): dictionary of related models from select_related +- `extracted` (`Dict`): dictionary with already extracted models #### extract\_models\_to\_dict\_of\_lists @@ -162,14 +162,14 @@ with all children models under their relation keys. **Arguments**: -- `model_type (Type[Model])`: parent model class -- `models (List[Model])`: list of models from which related models should be extracted. -- `select_dict (Dict)`: dictionary of related models from select_related -- `extracted (Dict)`: dictionary with already extracted models +- `model_type` (`Type[Model]`): parent model class +- `models` (`List[Model]`): list of models from which related models should be extracted. +- `select_dict` (`Dict`): dictionary of related models from select_related +- `extracted` (`Dict`): dictionary with already extracted models **Returns**: -`(Dict)`: dictionary of lists f related models +`Dict`: dictionary of lists f related models #### get\_relationship\_alias\_model\_and\_str @@ -183,12 +183,12 @@ constructed, extracts alias based on last relation leading to target model. **Arguments**: -- `related_parts (Union[List, List[str]])`: list of related names extracted from string -- `source_model (Type[Model])`: model from which relation starts +- `related_parts` (`Union[List, List[str]]`): list of related names extracted from string +- `source_model` (`Type[Model]`): model from which relation starts **Returns**: -`(Tuple[str, Type["Model"], str])`: table prefix, target model and relation string +`Tuple[str, Type["Model"], str]`: table prefix, target model and relation string #### \_process\_through\_field @@ -201,13 +201,13 @@ Helper processing through models as they need to be treated differently. **Arguments**: -- `related_parts (List[str])`: split relation string -- `relation (str)`: relation name -- `related_field ("ForeignKeyField")`: field with relation declaration -- `previous_model (Type["Model"])`: model from which relation is coming -- `previous_models (List[Type["Model"]])`: list of already visited models in relation chain +- `related_parts` (`List[str]`): split relation string +- `relation` (`str`): relation name +- `related_field` (`"ForeignKeyField"`): field with relation declaration +- `previous_model` (`Type["Model"]`): model from which relation is coming +- `previous_models` (`List[Type["Model"]]`): list of already visited models in relation chain **Returns**: -`(Tuple[Type["Model"], str, bool])`: previous_model, relation, is_through +`Tuple[Type["Model"], str, bool]`: previous_model, relation, is_through diff --git a/docs/api/relations/alias-manager.md b/docs/api/relations/alias-manager.md index 57c4885..c8c90ba 100644 --- a/docs/api/relations/alias-manager.md +++ b/docs/api/relations/alias-manager.md @@ -15,7 +15,7 @@ multiple different models in one join. **Returns**: -`(str)`: randomly generated alias +`str`: randomly generated alias ## AliasManager Objects @@ -27,6 +27,20 @@ class AliasManager() Keep all aliases of relations between different tables. One global instance is shared between all models. + +#### reversed\_aliases + +```python + | @property + | reversed_aliases() -> Dict +``` + +Returns swapped key-value pairs from aliases where alias is the key. + +**Returns**: + +`Dict`: dictionary of prefix to relation + #### prefixed\_columns @@ -43,13 +57,13 @@ List has to have sqlalchemy names of columns (ormar aliases) not the ormar ones. **Arguments**: -- `alias (str)`: alias of given table -- `table (sqlalchemy.Table)`: table from which fields should be aliased -- `fields (Optional[List[str]])`: fields to include +- `alias` (`str`): alias of given table +- `table` (`sqlalchemy.Table`): table from which fields should be aliased +- `fields` (`Optional[List[str]]`): fields to include **Returns**: -`(List[text])`: list of sqlalchemy text clauses with "column name as aliased name" +`List[text]`: list of sqlalchemy text clauses with "column name as aliased name" #### prefixed\_table\_name @@ -63,12 +77,12 @@ Creates text clause with table name with aliased name. **Arguments**: -- `alias (str)`: alias of given table -- `table (sqlalchemy.Table)`: table +- `alias` (`str`): alias of given table +- `table` (`sqlalchemy.Table`): table **Returns**: -`(sqlalchemy text clause)`: sqlalchemy text clause as "table_name aliased_name" +`sqlalchemy text clause`: sqlalchemy text clause as "table_name aliased_name" #### add\_relation\_type @@ -91,13 +105,13 @@ on one model as well as from multiple different models in one join. **Arguments**: -- `source_model (source Model)`: model with relation defined -- `relation_name (str)`: name of the relation to define -- `reverse_name (Optional[str])`: name of related_name fo given relation for m2m relations +- `source_model` (`source Model`): model with relation defined +- `relation_name` (`str`): name of the relation to define +- `reverse_name` (`Optional[str]`): name of related_name fo given relation for m2m relations **Returns**: -`(None)`: none +`None`: none #### add\_alias @@ -110,11 +124,11 @@ Adds alias to the dictionary of aliases under given key. **Arguments**: -- `alias_key (str)`: key of relation to generate alias for +- `alias_key` (`str`): key of relation to generate alias for **Returns**: -`(str)`: generated alias +`str`: generated alias #### resolve\_relation\_alias @@ -127,12 +141,12 @@ Given model and relation name returns the alias for this relation. **Arguments**: -- `from_model (source Model)`: model with relation defined -- `relation_name (str)`: name of the relation field +- `from_model` (`source Model`): model with relation defined +- `relation_name` (`str`): name of the relation field **Returns**: -`(str)`: alias of the relation +`str`: alias of the relation #### resolve\_relation\_alias\_after\_complex @@ -147,11 +161,11 @@ field definition. **Arguments**: -- `relation_field ("ForeignKeyField")`: field with direct relation definition -- `source_model (source Model)`: model with query starts -- `relation_str (str)`: string with relation joins defined +- `relation_field` (`"ForeignKeyField"`): field with direct relation definition +- `source_model` (`source Model`): model with query starts +- `relation_str` (`str`): string with relation joins defined **Returns**: -`(str)`: alias of the relation +`str`: alias of the relation diff --git a/docs/api/relations/queryset-proxy.md b/docs/api/relations/queryset-proxy.md index 3b46759..009c466 100644 --- a/docs/api/relations/queryset-proxy.md +++ b/docs/api/relations/queryset-proxy.md @@ -23,7 +23,7 @@ Returns queryset if it's set, AttributeError otherwise. **Returns**: -`(QuerySet)`: QuerySet +`QuerySet`: QuerySet #### queryset @@ -37,7 +37,7 @@ Set's the queryset. Initialized in RelationProxy. **Arguments**: -- `value (QuerySet)`: QuerySet +- `value` (`QuerySet`): QuerySet #### \_assign\_child\_to\_parent @@ -50,7 +50,7 @@ Registers child in parents RelationManager. **Arguments**: -- `child (Model)`: child to register on parent side. +- `child` (`Model`): child to register on parent side. #### \_register\_related @@ -63,7 +63,7 @@ Registers child/ children in parents RelationManager. **Arguments**: -- `child (Union[Model,List[Model]])`: child or list of children models to register. +- `child` (`Union[Model,List[Model]]`): child or list of children models to register. #### \_clean\_items\_on\_load @@ -85,8 +85,8 @@ Crete a through model instance in the database for m2m relations. **Arguments**: -- `kwargs (Any)`: dict of additional keyword arguments for through instance -- `child (Model)`: child model instance +- `kwargs` (`Any`): dict of additional keyword arguments for through instance +- `child` (`Model`): child model instance #### update\_through\_instance @@ -99,8 +99,8 @@ Updates a through model instance in the database for m2m relations. **Arguments**: -- `kwargs (Any)`: dict of additional keyword arguments for through instance -- `child (Model)`: child model instance +- `kwargs` (`Any`): dict of additional keyword arguments for through instance +- `child` (`Model`): child model instance #### upsert\_through\_instance @@ -114,8 +114,8 @@ it already exists, else creates one. **Arguments**: -- `kwargs (Any)`: dict of additional keyword arguments for through instance -- `child (Model)`: child model instance +- `kwargs` (`Any`): dict of additional keyword arguments for through instance +- `child` (`Model`): child model instance #### delete\_through\_instance @@ -128,7 +128,7 @@ Removes through model instance from the database for m2m relations. **Arguments**: -- `child (Model)`: child model instance +- `child` (`Model`): child model instance #### exists @@ -144,7 +144,7 @@ Actual call delegated to QuerySet. **Returns**: -`(bool)`: result of the check +`bool`: result of the check #### count @@ -160,7 +160,7 @@ Actual call delegated to QuerySet. **Returns**: -`(int)`: number of rows +`int`: number of rows #### max @@ -174,7 +174,7 @@ Returns max value of columns for rows matching the given criteria **Returns**: -`(Any)`: max value of column(s) +`Any`: max value of column(s) #### min @@ -188,7 +188,7 @@ Returns min value of columns for rows matching the given criteria **Returns**: -`(Any)`: min value of column(s) +`Any`: min value of column(s) #### sum @@ -202,7 +202,7 @@ Returns sum value of columns for rows matching the given criteria **Returns**: -`(int)`: sum value of columns +`int`: sum value of columns #### avg @@ -216,7 +216,7 @@ Returns avg value of columns for rows matching the given criteria **Returns**: -`(Union[int, float, List])`: avg value of columns +`Union[int, float, List]`: avg value of columns #### clear @@ -235,12 +235,12 @@ will be deleted, and not only removed from relation). **Arguments**: -- `keep_reversed (bool)`: flag if reverse models in reverse FK should be deleted or not, keep_reversed=False deletes them from database. +- `keep_reversed` (`bool`): flag if reverse models in reverse FK should be deleted **Returns**: -`(int)`: number of deleted models +`int`: number of deleted models #### first @@ -253,15 +253,18 @@ Gets the first row from the db ordered by primary key column ascending. Actual call delegated to QuerySet. +Passing args and/or kwargs is a shortcut and equals to calling +`filter(*args, **kwargs).first()`. + List of related models is cleared before the call. **Arguments**: -- `kwargs ()`: +- `kwargs`: **Returns**: -`(_asyncio.Future)`: +`_asyncio.Future`: #### get\_or\_none @@ -274,17 +277,18 @@ Get's the first row from the db meeting the criteria set by kwargs. If no criteria set it will return the last row in db sorted by pk. -Passing a criteria is actually calling filter(**kwargs) method described below. +Passing args and/or kwargs is a shortcut and equals to calling +`filter(*args, **kwargs).get_or_none()`. If not match is found None will be returned. **Arguments**: -- `kwargs (Any)`: fields names and proper value types +- `kwargs` (`Any`): fields names and proper value types **Returns**: -`(Model)`: returned model +`Model`: returned model #### get @@ -297,7 +301,8 @@ Get's the first row from the db meeting the criteria set by kwargs. If no criteria set it will return the last row in db sorted by pk. -Passing a criteria is actually calling filter(**kwargs) method described below. +Passing args and/or kwargs is a shortcut and equals to calling +`filter(*args, **kwargs).get()`. Actual call delegated to QuerySet. @@ -310,22 +315,23 @@ List of related models is cleared before the call. **Arguments**: -- `kwargs (Any)`: fields names and proper value types +- `kwargs` (`Any`): fields names and proper value types **Returns**: -`(Model)`: returned model +`Model`: returned model #### all ```python - | async all(*args: Any, **kwargs: Any) -> List[Optional["T"]] + | async all(*args: Any, **kwargs: Any) -> List["T"] ``` Returns all rows from a database for given model for set filter options. -Passing kwargs is a shortcut and equals to calling `filter(**kwrags).all()`. +Passing args and/or kwargs is a shortcut and equals to calling +`filter(*args, **kwargs).all()`. If there are no rows meeting the criteria an empty list is returned. @@ -335,11 +341,11 @@ List of related models is cleared before the call. **Arguments**: -- `kwargs (Any)`: fields names and proper value types +- `kwargs` (`Any`): fields names and proper value types **Returns**: -`(List[Model])`: list of returned models +`List[Model]`: list of returned models #### create @@ -359,11 +365,11 @@ Actual call delegated to QuerySet. **Arguments**: -- `kwargs (Any)`: fields names and proper value types +- `kwargs` (`Any`): fields names and proper value types **Returns**: -`(Model)`: created model +`Model`: created model #### update @@ -379,12 +385,12 @@ each=True flag to affect whole table. **Arguments**: -- `each (bool)`: flag if whole table should be affected if no filter is passed -- `kwargs (Any)`: fields names and proper value types +- `each` (`bool`): flag if whole table should be affected if no filter is passed +- `kwargs` (`Any`): fields names and proper value types **Returns**: -`(int)`: number of updated rows +`int`: number of updated rows #### get\_or\_create @@ -401,11 +407,11 @@ it creates a new one with given kwargs. **Arguments**: -- `kwargs (Any)`: fields names and proper value types +- `kwargs` (`Any`): fields names and proper value types **Returns**: -`(Model)`: returned or created Model +`Model`: returned or created Model #### update\_or\_create @@ -420,11 +426,11 @@ Actual call delegated to QuerySet. **Arguments**: -- `kwargs (Any)`: fields names and proper value types +- `kwargs` (`Any`): fields names and proper value types **Returns**: -`(Model)`: updated or created model +`Model`: updated or created model #### filter @@ -458,11 +464,11 @@ Actual call delegated to QuerySet. **Arguments**: -- `kwargs (Any)`: fields names and proper value types +- `kwargs` (`Any`): fields names and proper value types **Returns**: -`(QuerysetProxy)`: filtered QuerysetProxy +`QuerysetProxy`: filtered QuerysetProxy #### exclude @@ -487,11 +493,11 @@ Actual call delegated to QuerySet. **Arguments**: -- `kwargs (Any)`: fields names and proper value types +- `kwargs` (`Any`): fields names and proper value types **Returns**: -`(QuerysetProxy)`: filtered QuerysetProxy +`QuerysetProxy`: filtered QuerysetProxy #### select\_all @@ -514,13 +520,13 @@ Nested relations of those kind need to be loaded manually. **Arguments**: -- `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 +- `follow` (`bool`): flag to trigger deep save - **Returns**: -`(Model)`: reloaded Model +`Model`: reloaded Model #### select\_related @@ -543,11 +549,11 @@ Actual call delegated to QuerySet. **Arguments**: -- `related (Union[List, str])`: list of relation field names, can be linked by '__' to nest +- `related` (`Union[List, str]`): list of relation field names, can be linked by '__' to nest **Returns**: -`(QuerysetProxy)`: QuerysetProxy +`QuerysetProxy`: QuerysetProxy #### prefetch\_related @@ -571,11 +577,11 @@ Actual call delegated to QuerySet. **Arguments**: -- `related (Union[List, str])`: list of relation field names, can be linked by '__' to nest +- `related` (`Union[List, str]`): list of relation field names, can be linked by '__' to nest **Returns**: -`(QuerysetProxy)`: QuerysetProxy +`QuerysetProxy`: QuerysetProxy #### paginate @@ -591,12 +597,12 @@ Actual call delegated to QuerySet. **Arguments**: -- `page_size (int)`: numbers of items per page -- `page (int)`: page number +- `page_size` (`int`): numbers of items per page +- `page` (`int`): page number **Returns**: -`(QuerySet)`: QuerySet +`QuerySet`: QuerySet #### limit @@ -611,11 +617,11 @@ Actual call delegated to QuerySet. **Arguments**: -- `limit_count (int)`: number of models to limit +- `limit_count` (`int`): number of models to limit **Returns**: -`(QuerysetProxy)`: QuerysetProxy +`QuerysetProxy`: QuerysetProxy #### offset @@ -630,11 +636,11 @@ Actual call delegated to QuerySet. **Arguments**: -- `offset (int)`: numbers of models to offset +- `offset` (`int`): numbers of models to offset **Returns**: -`(QuerysetProxy)`: QuerysetProxy +`QuerysetProxy`: QuerysetProxy #### fields @@ -683,11 +689,11 @@ Actual call delegated to QuerySet. **Arguments**: -- `columns (Union[List, str, Set, Dict])`: columns to include +- `columns` (`Union[List, str, Set, Dict]`): columns to include **Returns**: -`(QuerysetProxy)`: QuerysetProxy +`QuerysetProxy`: QuerysetProxy #### exclude\_fields @@ -720,11 +726,11 @@ Actual call delegated to QuerySet. **Arguments**: -- `columns (Union[List, str, Set, Dict])`: columns to exclude +- `columns` (`Union[List, str, Set, Dict]`): columns to exclude **Returns**: -`(QuerysetProxy)`: QuerysetProxy +`QuerysetProxy`: QuerysetProxy #### order\_by @@ -762,9 +768,9 @@ Actual call delegated to QuerySet. **Arguments**: -- `columns (Union[List, str])`: columns by which models should be sorted +- `columns` (`Union[List, str]`): columns by which models should be sorted **Returns**: -`(QuerysetProxy)`: QuerysetProxy +`QuerysetProxy`: QuerysetProxy diff --git a/docs/api/relations/relation-manager.md b/docs/api/relations/relation-manager.md index 3b6c0e8..c43e2ad 100644 --- a/docs/api/relations/relation-manager.md +++ b/docs/api/relations/relation-manager.md @@ -21,11 +21,11 @@ Checks if relation with given name is already registered. **Arguments**: -- `item (str)`: name of attribute +- `item` (`str`): name of attribute **Returns**: -`(bool)`: result of the check +`bool`: result of the check #### get @@ -39,11 +39,11 @@ Actual call is delegated to Relation instance registered under relation name. **Arguments**: -- `name (str)`: name of the relation +- `name` (`str`): name of the relation **Returns**: -`(Optional[Union[Model, List[Model]])`: related model or list of related models if set +`Optional[Union[Model, List[Model]]`: related model or list of related models if set #### add @@ -62,9 +62,9 @@ on both ends. **Arguments**: -- `parent (Model)`: parent model on which relation should be registered -- `child (Model)`: child model to register -- `field (ForeignKeyField)`: field with relation definition +- `parent` (`Model`): parent model on which relation should be registered +- `child` (`Model`): child model to register +- `field` (`ForeignKeyField`): field with relation definition #### remove @@ -79,8 +79,8 @@ of relation from which you want to remove the child. **Arguments**: -- `name (str)`: name of the relation -- `child (Union[Model, Type[Model]])`: child to remove from relation +- `name` (`str`): name of the relation +- `child` (`Union[Model, Type[Model]]`): child to remove from relation #### remove\_parent @@ -96,9 +96,9 @@ of relation from which you want to remove the parent. **Arguments**: -- `item (Union[Model, Type[Model]])`: model with parent registered -- `parent (Model)`: parent Model -- `name (str)`: name of the relation +- `item` (`Union[Model, Type[Model]]`): model with parent registered +- `parent` (`Model`): parent Model +- `name` (`str`): name of the relation #### \_get @@ -111,11 +111,11 @@ Returns the actual relation and not the related model(s). **Arguments**: -- `name (str)`: name of the relation +- `name` (`str`): name of the relation **Returns**: -`(ormar.relations.relation.Relation)`: Relation instance +`ormar.relations.relation.Relation`: Relation instance #### \_get\_relation\_type @@ -128,11 +128,11 @@ Returns type of the relation declared on a field. **Arguments**: -- `field (BaseField)`: field with relation declaration +- `field` (`BaseField`): field with relation declaration **Returns**: -`(RelationType)`: type of the relation defined on field +`RelationType`: type of the relation defined on field #### \_add\_relation @@ -146,5 +146,5 @@ Adds Relation instance under field.name. **Arguments**: -- `field (BaseField)`: field with relation declaration +- `field` (`BaseField`): field with relation declaration diff --git a/docs/api/relations/relation-proxy.md b/docs/api/relations/relation-proxy.md index a896df6..f4d76af 100644 --- a/docs/api/relations/relation-proxy.md +++ b/docs/api/relations/relation-proxy.md @@ -23,7 +23,7 @@ _related_field_name property. **Returns**: -`(str)`: name of the related field +`str`: name of the related field #### \_\_getattribute\_\_ @@ -37,11 +37,11 @@ catch calls to them and delegate it to QuerySetProxy instead. **Arguments**: -- `item (str)`: name of attribute +- `item` (`str`): name of attribute **Returns**: -`(Any)`: value of attribute +`Any`: value of attribute #### \_\_getattr\_\_ @@ -54,11 +54,11 @@ Delegates calls for non existing attributes to QuerySetProxy. **Arguments**: -- `item (str)`: name of attribute/method +- `item` (`str`): name of attribute/method **Returns**: -`(method)`: method from QuerySetProxy if exists +`method`: method from QuerySetProxy if exists #### \_initialize\_queryset @@ -80,7 +80,7 @@ Checks if the QuerySetProxy is already set and ready. **Returns**: -`(bool)`: result of the check +`bool`: result of the check #### \_check\_if\_model\_saved @@ -105,7 +105,7 @@ to the parent model only, without need for user to filter them. **Returns**: -`(QuerySet)`: initialized QuerySet +`QuerySet`: initialized QuerySet #### remove @@ -124,8 +124,8 @@ will be deleted, and not only removed from relation). **Arguments**: -- `item (Model)`: child to remove from relation -- `keep_reversed (bool)`: flag if the reversed model should be kept or deleted too +- `item` (`Model`): child to remove from relation +- `keep_reversed` (`bool`): flag if the reversed model should be kept or deleted too #### add @@ -140,6 +140,6 @@ For ManyToMany relations through instance is automatically created. **Arguments**: -- `kwargs (Any)`: dict of additional keyword arguments for through instance -- `item (Model)`: child to add to relation +- `kwargs` (`Any`): dict of additional keyword arguments for through instance +- `item` (`Model`): child to add to relation diff --git a/docs/api/relations/relation.md b/docs/api/relations/relation.md index a20016b..0b1581b 100644 --- a/docs/api/relations/relation.md +++ b/docs/api/relations/relation.md @@ -37,11 +37,11 @@ related models already pre filtered by parent model. **Arguments**: -- `manager (RelationsManager)`: reference to relation manager -- `type_ (RelationType)`: type of the relation -- `field_name (str)`: name of the relation field -- `to (Type[Model])`: model to which relation leads to -- `through (Type[Model])`: model through which relation goes for m2m relations +- `manager` (`RelationsManager`): reference to relation manager +- `type_` (`RelationType`): type of the relation +- `field_name` (`str`): name of the relation field +- `to` (`Type[Model]`): model to which relation leads to +- `through` (`Type[Model]`): model through which relation goes for m2m relations #### \_clean\_related @@ -63,11 +63,11 @@ Find child model in RelationProxy if exists. **Arguments**: -- `child (Model)`: child model to find +- `child` (`Model`): child model to find **Returns**: -`(Optional[ind])`: index of child in RelationProxy +`Optional[ind]`: index of child in RelationProxy #### add @@ -81,7 +81,7 @@ it to the list in RelationProxy depending on relation type. **Arguments**: -- `child (Model)`: model to add to relation +- `child` (`Model`): model to add to relation #### remove @@ -95,7 +95,7 @@ it from the list in RelationProxy depending on relation type. **Arguments**: -- `child (Model)`: model to remove from relation +- `child` (`Model`): model to remove from relation #### get @@ -108,5 +108,5 @@ Return the related model or models from RelationProxy. **Returns**: -`(Optional[Union[List[Model], Model]])`: related model/models if set +`Optional[Union[List[Model], Model]]`: related model/models if set diff --git a/docs/api/relations/utils.md b/docs/api/relations/utils.md index 8711b3d..d43cbb0 100644 --- a/docs/api/relations/utils.md +++ b/docs/api/relations/utils.md @@ -13,11 +13,11 @@ changes one of the sides of the relation into weakref.proxy to model. **Arguments**: -- `to_field (ForeignKeyField)`: field with relation definition -- `parent (Model)`: parent model -- `child (Model)`: child model +- `to_field` (`ForeignKeyField`): field with relation definition +- `parent` (`Model`): parent model +- `child` (`Model`): child model **Returns**: -`(Tuple["Model", "Model", str, str])`: parent, child, child_name, to_name +`Tuple["Model", "Model", str, str]`: parent, child, child_name, to_name diff --git a/docs/api/signals/decorators.md b/docs/api/signals/decorators.md index 7fcbc0a..ebb13a8 100644 --- a/docs/api/signals/decorators.md +++ b/docs/api/signals/decorators.md @@ -12,13 +12,13 @@ Connect given function to all senders for given signal name. **Arguments**: -- `signal (str)`: name of the signal to register to -- `senders (Union[Type["Model"], List[Type["Model"]]])`: one or a list of "Model" classes that should have the signal receiver registered +- `signal` (`str`): name of the signal to register to +- `senders` (`Union[Type["Model"], List[Type["Model"]]]`): one or a list of "Model" classes **Returns**: -`(Callable)`: returns the original function untouched +`Callable`: returns the original function untouched #### post\_save @@ -31,12 +31,12 @@ Connect given function to all senders for post_save signal. **Arguments**: -- `senders (Union[Type["Model"], List[Type["Model"]]])`: one or a list of "Model" classes that should have the signal receiver registered +- `senders` (`Union[Type["Model"], List[Type["Model"]]]`): one or a list of "Model" classes **Returns**: -`(Callable)`: returns the original function untouched +`Callable`: returns the original function untouched #### post\_update @@ -49,12 +49,12 @@ Connect given function to all senders for post_update signal. **Arguments**: -- `senders (Union[Type["Model"], List[Type["Model"]]])`: one or a list of "Model" classes that should have the signal receiver registered +- `senders` (`Union[Type["Model"], List[Type["Model"]]]`): one or a list of "Model" classes **Returns**: -`(Callable)`: returns the original function untouched +`Callable`: returns the original function untouched #### post\_delete @@ -67,12 +67,12 @@ Connect given function to all senders for post_delete signal. **Arguments**: -- `senders (Union[Type["Model"], List[Type["Model"]]])`: one or a list of "Model" classes that should have the signal receiver registered +- `senders` (`Union[Type["Model"], List[Type["Model"]]]`): one or a list of "Model" classes **Returns**: -`(Callable)`: returns the original function untouched +`Callable`: returns the original function untouched #### pre\_save @@ -85,12 +85,12 @@ Connect given function to all senders for pre_save signal. **Arguments**: -- `senders (Union[Type["Model"], List[Type["Model"]]])`: one or a list of "Model" classes that should have the signal receiver registered +- `senders` (`Union[Type["Model"], List[Type["Model"]]]`): one or a list of "Model" classes **Returns**: -`(Callable)`: returns the original function untouched +`Callable`: returns the original function untouched #### pre\_update @@ -103,12 +103,12 @@ Connect given function to all senders for pre_update signal. **Arguments**: -- `senders (Union[Type["Model"], List[Type["Model"]]])`: one or a list of "Model" classes that should have the signal receiver registered +- `senders` (`Union[Type["Model"], List[Type["Model"]]]`): one or a list of "Model" classes **Returns**: -`(Callable)`: returns the original function untouched +`Callable`: returns the original function untouched #### pre\_delete @@ -121,12 +121,12 @@ Connect given function to all senders for pre_delete signal. **Arguments**: -- `senders (Union[Type["Model"], List[Type["Model"]]])`: one or a list of "Model" classes that should have the signal receiver registered +- `senders` (`Union[Type["Model"], List[Type["Model"]]]`): one or a list of "Model" classes **Returns**: -`(Callable)`: returns the original function untouched +`Callable`: returns the original function untouched #### pre\_relation\_add @@ -139,12 +139,12 @@ Connect given function to all senders for pre_relation_add signal. **Arguments**: -- `senders (Union[Type["Model"], List[Type["Model"]]])`: one or a list of "Model" classes that should have the signal receiver registered +- `senders` (`Union[Type["Model"], List[Type["Model"]]]`): one or a list of "Model" classes **Returns**: -`(Callable)`: returns the original function untouched +`Callable`: returns the original function untouched #### post\_relation\_add @@ -157,12 +157,12 @@ Connect given function to all senders for post_relation_add signal. **Arguments**: -- `senders (Union[Type["Model"], List[Type["Model"]]])`: one or a list of "Model" classes that should have the signal receiver registered +- `senders` (`Union[Type["Model"], List[Type["Model"]]]`): one or a list of "Model" classes **Returns**: -`(Callable)`: returns the original function untouched +`Callable`: returns the original function untouched #### pre\_relation\_remove @@ -175,12 +175,12 @@ Connect given function to all senders for pre_relation_remove signal. **Arguments**: -- `senders (Union[Type["Model"], List[Type["Model"]]])`: one or a list of "Model" classes that should have the signal receiver registered +- `senders` (`Union[Type["Model"], List[Type["Model"]]]`): one or a list of "Model" classes **Returns**: -`(Callable)`: returns the original function untouched +`Callable`: returns the original function untouched #### post\_relation\_remove @@ -193,10 +193,10 @@ Connect given function to all senders for post_relation_remove signal. **Arguments**: -- `senders (Union[Type["Model"], List[Type["Model"]]])`: one or a list of "Model" classes that should have the signal receiver registered +- `senders` (`Union[Type["Model"], List[Type["Model"]]]`): one or a list of "Model" classes **Returns**: -`(Callable)`: returns the original function untouched +`Callable`: returns the original function untouched diff --git a/docs/api/signals/signal.md b/docs/api/signals/signal.md index cc09308..34f70b9 100644 --- a/docs/api/signals/signal.md +++ b/docs/api/signals/signal.md @@ -12,11 +12,11 @@ Checks if function accepts **kwargs. **Arguments**: -- `func (function)`: function which signature needs to be checked +- `func` (`function`): function which signature needs to be checked **Returns**: -`(bool)`: result of the check +`bool`: result of the check #### make\_id @@ -29,11 +29,11 @@ Creates id of a function or method to be used as key to store signal **Arguments**: -- `target (Any)`: target which id we want +- `target` (`Any`): target which id we want **Returns**: -`(int)`: id of the target +`int`: id of the target ## Signal Objects @@ -61,7 +61,7 @@ or not accept **kwargs **Arguments**: -- `receiver (Callable)`: receiver function +- `receiver` (`Callable`): receiver function #### disconnect @@ -74,11 +74,11 @@ Removes the receiver function from the signal. **Arguments**: -- `receiver (Callable)`: receiver function +- `receiver` (`Callable`): receiver function **Returns**: -`(bool)`: flag if receiver was removed +`bool`: flag if receiver was removed #### send @@ -91,8 +91,8 @@ Notifies all receiver functions with given kwargs **Arguments**: -- `sender (Type["Model"])`: model that sends the signal -- `kwargs (Any)`: arguments passed to receivers +- `sender` (`Type["Model"]`): model that sends the signal +- `kwargs` (`Any`): arguments passed to receivers ## SignalEmitter Objects diff --git a/docs/queries/index.md b/docs/queries/index.md index 3fb94af..4cb314c 100644 --- a/docs/queries/index.md +++ b/docs/queries/index.md @@ -66,6 +66,21 @@ To read more about any specific section or function please refer to the details !!!tip To read more about any or all of those functions visit [read](./read.md) section. +### [Read raw data from database](./raw-data.md) + +Instead of ormar models return raw data in form list of dictionaries or tuples. + +* `values(fields = None, exclude_through = False) -> List[Dict]` +* `values_list(fields = None, exclude_through = False, flatten = False) -> List` + + +* `QuerysetProxy` + * `QuerysetProxy.values(fields = None, exclude_through = False)` method + * `QuerysetProxy.values_list(fields = None, exclude_through= False, flatten = False)` method + +!!!tip + To read more about any or all of those functions visit [raw data](./raw-data.md) section. + ### [Update data in database](./update.md) * `update(each: bool = False, **kwargs) -> int` diff --git a/docs/queries/raw-data.md b/docs/queries/raw-data.md new file mode 100644 index 0000000..df67088 --- /dev/null +++ b/docs/queries/raw-data.md @@ -0,0 +1,359 @@ +# Return raw data + +Following methods allow you to execute a query but instead of returning ormar models those will return list of dicts or tuples. + +* `values(fields = None, exclude_through = False) -> List[Dict]` +* `values_list(fields = None, exclude_through = False, flatten = False) -> List` + + +* `QuerysetProxy` + * `QuerysetProxy.values(fields = None, exclude_through = False)` method + * `QuerysetProxy.values_list(fields = None, exclude_through= False, flatten = False)` method + +!!!danger + Note that `values` and `values_list` skips parsing the result to ormar models so skips also the validation of the result! + +!!!warning + Note that each entry in a result list is one to one reflection of a query result row. + Since rows are not parsed if you have one-to-many or many-to-many relation expect + duplicated columns values in result entries if one parent row have multiple related rows. + + +## values + +`values(fields: Union[List, str, Set, Dict] = None, exclude_through: bool = False) -> List[Dict]` + +Return a list of dictionaries representing the values of the columns coming from the database. + +You can select a subset of fields with fields parameter, that accepts the same set of parameters as `fields()` method. + +Note that passing fields to `values(fields)` is actually a shortcut for calling `fields(fields).values()`. + +!!!tip + To read more about what you can pass to fields and how to select nested models fields read [selecting columns](./select-columns.md#fields) docs + +You can limit the number of rows by providing conditions in `filter()` and `exclude()`, but note that even if only one row (or no rows!) match your criteria you will return a list in response. + +Example: + +```python +# declared models + +class Category(ormar.Model): + class Meta(BaseMeta): + tablename = "categories" + + id: int = ormar.Integer(primary_key=True) + name: str = ormar.String(max_length=40) + sort_order: int = ormar.Integer(nullable=True) + + +class Post(ormar.Model): + class Meta(BaseMeta): + tablename = "posts" + + id: int = ormar.Integer(primary_key=True) + name: str = ormar.String(max_length=200) + category: Optional[Category] = ormar.ForeignKey(Category) + +# sample data +news = await Category(name="News", sort_order=0).save() +await Post(name="Ormar strikes again!", category=news).save() +await Post(name="Why don't you use ormar yet?", category=news).save() +await Post(name="Check this out, ormar now for free", category=news).save() +``` + +Access Post models: + +```python +posts = await Post.objects.values() +assert posts == [ + {"id": 1, "name": "Ormar strikes again!", "category": 1}, + {"id": 2, "name": "Why don't you use ormar yet?", "category": 1}, + {"id": 3, "name": "Check this out, ormar now for free", "category": 1}, +] +``` + +To select also related models use `select_related` or `prefetch_related`. + +Note how nested models columns will be prefixed with full relation path coming from the main model (the one used in a query). + + +```python +# declare models + +class User(ormar.Model): + class Meta(BaseMeta): + pass + + id: int = ormar.Integer(primary_key=True) + name: str = ormar.String(max_length=100) + + +class Role(ormar.Model): + class Meta(BaseMeta): + pass + + id: int = ormar.Integer(primary_key=True) + name: str = ormar.String(max_length=100) + users: List[User] = ormar.ManyToMany(User) + +# sample data +creator = await User(name="Anonymous").save() +admin = await Role(name="admin").save() +editor = await Role(name="editor").save() +await creator.roles.add(admin) +await creator.roles.add(editor) +``` + +Select user with roles + +```python +user = await User.objects.select_related("roles").values() +# note nested prefixes: roleuser and roles +assert user == [ + { + "id": 1, + "name": "Anonymous", + "roleuser__id": 1, + "roleuser__role": 1, + "roleuser__user": 1, + "roles__id": 1, + "roles__name": "admin", + }, + { + "id": 1, + "name": "Anonymous", + "roleuser__id": 2, + "roleuser__role": 2, + "roleuser__user": 1, + "roles__id": 2, + "roles__name": "editor", + }, +] +``` + +!!!note + Note how role to users relation is a `ManyToMany` relation so by default you also get through model columns. + +Combine select related and fields to select only 3 fields. + +Note that we also exclude through model as by definition every model included in a join but without any reference in fields is assumed to be selected in full (all fields included). + +!!!note + Note that in contrary to other queryset methods here you can exclude the + in-between models but keep the end columns, which does not make sense + when parsing the raw data into models. + + So in relation category -> category_x_post -> post -> user you can exclude + category_x_post and post models but can keep the user one. (in ormar model + context that is not possible as if you would exclude through and post model + there would be no way to reach user model from category model). + +```python +user = ( + await Role.objects.select_related("users__categories") + .filter(name="admin") + .fields({"name": ..., "users": {"name": ..., "categories": {"name"}}}) + .exclude_fields("roleuser") + .values() + ) +assert user == [ + { + "name": "admin", + "users__name": "Anonymous", + "users__categories__name": "News", + } +] +``` + +If you have multiple ManyToMany models in your query you would have to exclude each through model manually. + +To avoid this burden `ormar` provides you with `exclude_through=False` parameter. +If you set this flag to True **all through models will be fully excluded**. + + +```python +# equivalent to query above, note lack of exclude_fields call +user = ( + await Role.objects.select_related("users__categories") + .filter(name="admin") + .fields({"name": ..., "users": {"name": ..., "categories": {"name"}}}) + .values(exclude_through=True) +) +assert user == [ + { + "name": "admin", + "users__name": "Anonymous", + "users__categories__name": "News", + } +] +``` + +## values_list + +`values_list(fields: Union[List, str, Set, Dict] = None, flatten: bool = False, exclude_through: bool = False) -> List` + +Return a list of tuples representing the values of the columns coming from the database. + +You can select a subset of fields with fields parameter, that accepts the same set of parameters as `fields()` method. + +Note that passing fields to `values_list(fields)` is actually a shortcut for calling `fields(fields).values_list()`. + +!!!tip + To read more about what you can pass to fields and how to select nested models fields read [selecting columns](./select-columns.md#fields) docs + +If you select only one column/field you can pass `flatten=True` which will return you a list of values instead of list of one element tuples. + +!!!warning + Setting `flatten=True` if more than one (or none which means all) fields are selected will raise `QueryDefinitionError` exception. + +You can limit the number of rows by providing conditions in `filter()` and `exclude()`, but note that even if only one row (or no rows!) match your criteria you will return a list in response. + +Example: + +```python +# declared models + +class Category(ormar.Model): + class Meta(BaseMeta): + tablename = "categories" + + id: int = ormar.Integer(primary_key=True) + name: str = ormar.String(max_length=40) + sort_order: int = ormar.Integer(nullable=True) + + +class Post(ormar.Model): + class Meta(BaseMeta): + tablename = "posts" + + id: int = ormar.Integer(primary_key=True) + name: str = ormar.String(max_length=200) + category: Optional[Category] = ormar.ForeignKey(Category) + +# sample data +news = await Category(name="News", sort_order=0).save() +await Post(name="Ormar strikes again!", category=news).save() +await Post(name="Why don't you use ormar yet?", category=news).save() +await Post(name="Check this out, ormar now for free", category=news).save() +``` + +Access Post models: + +```python +posts = await Post.objects.values_list() +# note how columns refer to id, name and category (fk) +assert posts == [ + (1, "Ormar strikes again!", 1), + (2, "Why don't you use ormar yet?", 1), + (3, "Check this out, ormar now for free", 1), +] +``` + +To select also related models use `select_related` or `prefetch_related`. + +Let's complicate the relation and modify the previously mentioned Category model to refer to User model. + +```python +class Category(ormar.Model): + class Meta(BaseMeta): + tablename = "categories" + + id: int = ormar.Integer(primary_key=True) + name: str = ormar.String(max_length=40) + sort_order: int = ormar.Integer(nullable=True) + # new column below + created_by: Optional[User] = ormar.ForeignKey(User, related_name="categories") + +``` + +Now create the sample data with link to user. + +```python +creator = await User(name="Anonymous").save() +admin = await Role(name="admin").save() +editor = await Role(name="editor").save() +await creator.roles.add(admin) +await creator.roles.add(editor) +news = await Category(name="News", sort_order=0, created_by=creator).save() +``` + +Combine select related and fields to select only 3 fields. + +Note that we also exclude through model as by definition every model included in a join but without any reference in fields is assumed to be selected in full (all fields included). + +!!!note + Note that in contrary to other queryset methods here you can exclude the + in-between models but keep the end columns, which does not make sense + when parsing the raw data into models. + + So in relation category -> category_x_post -> post -> user you can exclude + category_x_post and post models but can keep the user one. (in ormar model + context that is not possible as if you would exclude through and post model + there would be no way to reach user model from category model). + +```python +user = ( + await Role.objects.select_related("users__categories") + .filter(name="admin") + .fields({"name": ..., "users": {"name": ..., "categories": {"name"}}}) + .exclude_fields("roleuser") + .values_list() + ) +assert user == [("admin", "Anonymous", "News")] +``` + +If you have multiple ManyToMany models in your query you would have to exclude each through model manually. + +To avoid this burden `ormar` provides you with `exclude_through=False` parameter. +If you set this flag to True **all through models will be fully excluded**. + +```python +# equivalent to query above, note lack of exclude_fields call +user = ( + await Role.objects.select_related("users__categories") + .filter(name="admin") + .fields({"name": ..., "users": {"name": ..., "categories": {"name"}}}) + .values_list(exclude_through=True) + ) +assert user == [("admin", "Anonymous", "News")] +``` + +Use flatten to get list of values. + +```python +# using flatten with more than one field will raise exception! +await Role.objects.fields({"name", "id"}).values_list(flatten=True) + +# proper usage +roles = await Role.objects.fields("name").values_list(flatten=True) +assert roles == ["admin", "editor"] +``` + +## QuerysetProxy methods + +When access directly the related `ManyToMany` field as well as `ReverseForeignKey` +returns the list of related models. + +But at the same time it exposes subset of QuerySet API, so you can filter, create, +select related etc related models directly from parent model. + +!!!warning + Because using `values` and `values_list` skips parsing of the models and validation, in contrast to all other read methods in querysetproxy those 2 **does not clear currently loaded related models** and **does not overwrite the currently loaded models** with result of own call! + +### values + +Works exactly the same as [values](./#values) function above but allows you to fetch related +objects from other side of the relation. + +!!!tip + To read more about `QuerysetProxy` visit [querysetproxy][querysetproxy] section + +### values_list + +Works exactly the same as [values_list](./#values_list) function above but allows +you to query or create related objects from other side of the relation. + +!!!tip + To read more about `QuerysetProxy` visit [querysetproxy][querysetproxy] section diff --git a/mkdocs.yml b/mkdocs.yml index da57325..57f08a1 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -31,6 +31,7 @@ nav: - queries/select-columns.md - queries/pagination-and-rows-number.md - queries/aggregations.md + - Return raw data: queries/raw-data.md - Signals: signals.md - Transactions: transactions.md - Use with Fastapi: @@ -44,6 +45,8 @@ nav: - Api (BETA): - Index: api/index.md - Models: + - Helpers: + - api/models/descriptors/descriptors.md - Helpers: - api/models/helpers/models.md - api/models/helpers/pydantic.md @@ -82,6 +85,7 @@ nav: - Limit Query: api/query-set/limit-query.md - Offset Query: api/query-set/offset-query.md - Field Accessor: api/query-set/field-accessor.md + - Reverse Alias Resolver: api/query-set/reverse-alias-resolver.md - api/query-set/utils.md - Relations: - Relation Manager: api/relations/relation-manager.md diff --git a/pydoc-markdown.yml b/pydoc-markdown.yml index 7434f2d..175b903 100644 --- a/pydoc-markdown.yml +++ b/pydoc-markdown.yml @@ -130,6 +130,9 @@ renderer: - title: Field accessor contents: - queryset.field_accessor.* + - title: Reverse Alias Resolver + contents: + - queryset.reverse_alias_resolver.* - title: Utils contents: - queryset.utils.*