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

next part of the docs and api documentation in beta ver

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

127
docs/api/relations/alias-manager.md Normal file
View File

@ -0,0 +1,127 @@
<a name="relations.alias_manager"></a>
# relations.alias\_manager
<a name="relations.alias_manager.get_table_alias"></a>
#### get\_table\_alias
```python
get_table_alias() -> str
```
Creates a random string that is used to alias tables in joins.
It's necessary that each relation has it's own aliases cause you can link
to the same target tables from multiple fields on one model as well as from
multiple different models in one join.
**Returns**:
`(str)`: randomly generated alias
<a name="relations.alias_manager.AliasManager"></a>
## AliasManager Objects
```python
class AliasManager()
```
Keep all aliases of relations between different tables.
One global instance is shared between all models.
<a name="relations.alias_manager.AliasManager.__init__"></a>
#### \_\_init\_\_
```python
| __init__() -> None
```
<a name="relations.alias_manager.AliasManager.prefixed_columns"></a>
#### prefixed\_columns
```python
| @staticmethod
| prefixed_columns(alias: str, table: sqlalchemy.Table, fields: List = None) -> List[text]
```
Creates a list of aliases sqlalchemy text clauses from
string alias and sqlalchemy.Table.
Optional list of fields to include can be passed to extract only those columns.
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
**Returns**:
`(List[text])`: list of sqlalchemy text clauses with "column name as aliased name"
<a name="relations.alias_manager.AliasManager.prefixed_table_name"></a>
#### prefixed\_table\_name
```python
| @staticmethod
| prefixed_table_name(alias: str, name: str) -> text
```
Creates text clause with table name with aliased name.
**Arguments**:
- `alias (str)`: alias of given table
- `name (str)`: table name
**Returns**:
`(sqlalchemy text clause)`: sqlalchemy text clause as "table_name aliased_name"
<a name="relations.alias_manager.AliasManager.add_relation_type"></a>
#### add\_relation\_type
```python
| add_relation_type(source_model: Type["Model"], relation_name: str, reverse_name: str = None, is_multi: bool = False) -> None
```
Registers the relations defined in ormar models.
Given the relation it registers also the reverse side of this relation.
Used by both ForeignKey and ManyToMany relations.
Each relation is registered as Model name and relation name.
Each alias registered has to be unique.
Aliases are used to construct joins to assure proper links between tables.
That way you can link to the same target tables from multiple fields
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
- `is_multi (bool)`: flag if relation being registered is a through m2m model
**Returns**:
`(None)`: none
<a name="relations.alias_manager.AliasManager.resolve_relation_alias"></a>
#### resolve\_relation\_alias
```python
| resolve_relation_alias(from_model: Type["Model"], relation_name: str) -> str
```
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
**Returns**:
`(str)`: alias of the relation

595
docs/api/relations/queryset-proxy.md Normal file
View File

@ -0,0 +1,595 @@
<a name="relations.querysetproxy"></a>
# relations.querysetproxy
<a name="relations.querysetproxy.QuerysetProxy"></a>
## QuerysetProxy Objects
```python
class QuerysetProxy(ormar.QuerySetProtocol)
```
Exposes QuerySet methods on relations, but also handles creating and removing
of through Models for m2m relations.
<a name="relations.querysetproxy.QuerysetProxy.__init__"></a>
#### \_\_init\_\_
```python
| __init__(relation: "Relation", type_: "RelationType", qryset: "QuerySet" = None) -> None
```
<a name="relations.querysetproxy.QuerysetProxy.queryset"></a>
#### queryset
```python
| @property
| queryset() -> "QuerySet"
```
Returns queryset if it's set, AttributeError otherwise.
**Returns**:
`(QuerySet)`: QuerySet
<a name="relations.querysetproxy.QuerysetProxy.queryset"></a>
#### queryset
```python
| @queryset.setter
| queryset(value: "QuerySet") -> None
```
Set's the queryset. Initialized in RelationProxy.
**Arguments**:
- `value (QuerySet)`: QuerySet
<a name="relations.querysetproxy.QuerysetProxy._assign_child_to_parent"></a>
#### \_assign\_child\_to\_parent
```python
| _assign_child_to_parent(child: Optional["T"]) -> None
```
Registers child in parents RelationManager.
**Arguments**:
- `child (Model)`: child to register on parent side.
<a name="relations.querysetproxy.QuerysetProxy._register_related"></a>
#### \_register\_related
```python
| _register_related(child: Union["T", Sequence[Optional["T"]]]) -> None
```
Registers child/ children in parents RelationManager.
**Arguments**:
- `child (Union[Model,List[Model]])`: child or list of children models to register.
<a name="relations.querysetproxy.QuerysetProxy._clean_items_on_load"></a>
#### \_clean\_items\_on\_load
```python
| _clean_items_on_load() -> None
```
Cleans the current list of the related models.
<a name="relations.querysetproxy.QuerysetProxy.create_through_instance"></a>
#### create\_through\_instance
```python
| async create_through_instance(child: "T") -> None
```
Crete a through model instance in the database for m2m relations.
**Arguments**:
- `child (Model)`: child model instance
<a name="relations.querysetproxy.QuerysetProxy.delete_through_instance"></a>
#### delete\_through\_instance
```python
| async delete_through_instance(child: "T") -> None
```
Removes through model instance from the database for m2m relations.
**Arguments**:
- `child (Model)`: child model instance
<a name="relations.querysetproxy.QuerysetProxy.exists"></a>
#### exists
```python
| async exists() -> bool
```
Returns a bool value to confirm if there are rows matching the given criteria
(applied with `filter` and `exclude` if set).
Actual call delegated to QuerySet.
**Returns**:
`(bool)`: result of the check
<a name="relations.querysetproxy.QuerysetProxy.count"></a>
#### count
```python
| async count() -> int
```
Returns number of rows matching the given criteria
(applied with `filter` and `exclude` if set before).
Actual call delegated to QuerySet.
**Returns**:
`(int)`: number of rows
<a name="relations.querysetproxy.QuerysetProxy.clear"></a>
#### clear
```python
| async clear(keep_reversed: bool = True) -> int
```
Removes all related models from given relation.
Removes all through models for m2m relation.
For reverse FK relations keep_reversed flag marks if the reversed models
should be kept or deleted from the database too (False means that models
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.
**Returns**:
`(int)`: number of deleted models
<a name="relations.querysetproxy.QuerysetProxy.first"></a>
#### first
```python
| async first(**kwargs: Any) -> "Model"
```
Gets the first row from the db ordered by primary key column ascending.
Actual call delegated to QuerySet.
List of related models is cleared before the call.
**Arguments**:
- `kwargs ()`:
**Returns**:
`(_asyncio.Future)`:
<a name="relations.querysetproxy.QuerysetProxy.get"></a>
#### get
```python
| async get(**kwargs: Any) -> "Model"
```
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.
Actual call delegated to QuerySet.
List of related models is cleared before the call.
**Raises**:
- `NoMatch`: if no rows are returned
- `MultipleMatches`: if more than 1 row is returned.
**Arguments**:
- `kwargs (Any)`: fields names and proper value types
**Returns**:
`(Model)`: returned model
<a name="relations.querysetproxy.QuerysetProxy.all"></a>
#### all
```python
| async all(**kwargs: Any) -> Sequence[Optional["Model"]]
```
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()`.
If there are no rows meeting the criteria an empty list is returned.
Actual call delegated to QuerySet.
List of related models is cleared before the call.
**Arguments**:
- `kwargs (Any)`: fields names and proper value types
**Returns**:
`(List[Model])`: list of returned models
<a name="relations.querysetproxy.QuerysetProxy.create"></a>
#### create
```python
| async create(**kwargs: Any) -> "Model"
```
Creates the model instance, saves it in a database and returns the updates model
(with pk populated if not passed and autoincrement is set).
The allowed kwargs are `Model` fields names and proper value types.
For m2m relation the through model is created automatically.
Actual call delegated to QuerySet.
**Arguments**:
- `kwargs (Any)`: fields names and proper value types
**Returns**:
`(Model)`: created model
<a name="relations.querysetproxy.QuerysetProxy.get_or_create"></a>
#### get\_or\_create
```python
| async get_or_create(**kwargs: Any) -> "Model"
```
Combination of create and get methods.
Tries to get a row meeting the criteria fro kwargs
and if `NoMatch` exception is raised
it creates a new one with given kwargs.
**Arguments**:
- `kwargs (Any)`: fields names and proper value types
**Returns**:
`(Model)`: returned or created Model
<a name="relations.querysetproxy.QuerysetProxy.update_or_create"></a>
#### update\_or\_create
```python
| async update_or_create(**kwargs: Any) -> "Model"
```
Updates the model, or in case there is no match in database creates a new one.
Actual call delegated to QuerySet.
**Arguments**:
- `kwargs (Any)`: fields names and proper value types
**Returns**:
`(Model)`: updated or created model
<a name="relations.querysetproxy.QuerysetProxy.filter"></a>
#### filter
```python
| filter(**kwargs: Any) -> "QuerysetProxy"
```
Allows you to filter by any `Model` attribute/field
as well as to fetch instances, with a filter across an FK relationship.
You can use special filter suffix to change the filter operands:
* exact - like `album__name__exact='Malibu'` (exact match)
* iexact - like `album__name__iexact='malibu'` (exact match case insensitive)
* contains - like `album__name__contains='Mal'` (sql like)
* icontains - like `album__name__icontains='mal'` (sql like case insensitive)
* in - like `album__name__in=['Malibu', 'Barclay']` (sql in)
* gt - like `position__gt=3` (sql >)
* gte - like `position__gte=3` (sql >=)
* lt - like `position__lt=3` (sql <)
* lte - like `position__lte=3` (sql <=)
* startswith - like `album__name__startswith='Mal'` (exact start match)
* istartswith - like `album__name__istartswith='mal'` (case insensitive)
* endswith - like `album__name__endswith='ibu'` (exact end match)
* iendswith - like `album__name__iendswith='IBU'` (case insensitive)
Actual call delegated to QuerySet.
**Arguments**:
- `kwargs (Any)`: fields names and proper value types
**Returns**:
`(QuerysetProxy)`: filtered QuerysetProxy
<a name="relations.querysetproxy.QuerysetProxy.exclude"></a>
#### exclude
```python
| exclude(**kwargs: Any) -> "QuerysetProxy"
```
Works exactly the same as filter and all modifiers (suffixes) are the same,
but returns a *not* condition.
So if you use `filter(name='John')` which is `where name = 'John'` in SQL,
the `exclude(name='John')` equals to `where name <> 'John'`
Note that all conditions are joined so if you pass multiple values it
becomes a union of conditions.
`exclude(name='John', age>=35)` will become
`where not (name='John' and age>=35)`
Actual call delegated to QuerySet.
**Arguments**:
- `kwargs (Any)`: fields names and proper value types
**Returns**:
`(QuerysetProxy)`: filtered QuerysetProxy
<a name="relations.querysetproxy.QuerysetProxy.select_related"></a>
#### select\_related
```python
| select_related(related: Union[List, str]) -> "QuerysetProxy"
```
Allows to prefetch related models during the same query.
**With `select_related` always only one query is run against the database**,
meaning that one (sometimes complicated) join is generated and later nested
models are processed in python.
To fetch related model use `ForeignKey` names.
To chain related `Models` relation use double underscores between names.
Actual call delegated to QuerySet.
**Arguments**:
- `related (Union[List, str])`: list of relation field names, can be linked by '__' to nest
**Returns**:
`(QuerysetProxy)`: QuerysetProxy
<a name="relations.querysetproxy.QuerysetProxy.prefetch_related"></a>
#### prefetch\_related
```python
| prefetch_related(related: Union[List, str]) -> "QuerysetProxy"
```
Allows to prefetch related models during query - but opposite to
`select_related` each subsequent model is fetched in a separate database query.
**With `prefetch_related` always one query per Model is run against the
database**, meaning that you will have multiple queries executed one
after another.
To fetch related model use `ForeignKey` names.
To chain related `Models` relation use double underscores between names.
Actual call delegated to QuerySet.
**Arguments**:
- `related (Union[List, str])`: list of relation field names, can be linked by '__' to nest
**Returns**:
`(QuerysetProxy)`: QuerysetProxy
<a name="relations.querysetproxy.QuerysetProxy.limit"></a>
#### limit
```python
| limit(limit_count: int) -> "QuerysetProxy"
```
You can limit the results to desired number of parent models.
Actual call delegated to QuerySet.
**Arguments**:
- `limit_count (int)`: number of models to limit
**Returns**:
`(QuerysetProxy)`: QuerysetProxy
<a name="relations.querysetproxy.QuerysetProxy.offset"></a>
#### offset
```python
| offset(offset: int) -> "QuerysetProxy"
```
You can also offset the results by desired number of main models.
Actual call delegated to QuerySet.
**Arguments**:
- `offset (int)`: numbers of models to offset
**Returns**:
`(QuerysetProxy)`: QuerysetProxy
<a name="relations.querysetproxy.QuerysetProxy.fields"></a>
#### fields
```python
| fields(columns: Union[List, str, Set, Dict]) -> "QuerysetProxy"
```
With `fields()` you can select subset of model columns to limit the data load.
Note that `fields()` and `exclude_fields()` works both for main models
(on normal queries like `get`, `all` etc.)
as well as `select_related` and `prefetch_related`
models (with nested notation).
You can select specified fields by passing a `str, List[str], Set[str] or
dict` with nested definition.
To include related models use notation
`{related_name}__{column}[__{optional_next} etc.]`.
`fields()` can be called several times, building up the columns to select.
If you include related models into `select_related()` call but you won't specify
columns for those models in fields - implies a list of all fields for
those nested models.
Mandatory fields cannot be excluded as it will raise `ValidationError`,
to exclude a field it has to be nullable.
Pk column cannot be excluded - it's always auto added even if
not explicitly included.
You can also pass fields to include as dictionary or set.
To mark a field as included in a dictionary use it's name as key
and ellipsis as value.
To traverse nested models use nested dictionaries.
To include fields at last level instead of nested dictionary a set can be used.
To include whole nested model specify model related field name and ellipsis.
Actual call delegated to QuerySet.
**Arguments**:
- `columns (Union[List, str, Set, Dict])`: columns to include
**Returns**:
`(QuerysetProxy)`: QuerysetProxy
<a name="relations.querysetproxy.QuerysetProxy.exclude_fields"></a>
#### exclude\_fields
```python
| exclude_fields(columns: Union[List, str, Set, Dict]) -> "QuerysetProxy"
```
With `exclude_fields()` you can select subset of model columns that will
be excluded to limit the data load.
It's the opposite of `fields()` method so check documentation above
to see what options are available.
Especially check above how you can pass also nested dictionaries
and sets as a mask to exclude fields from whole hierarchy.
Note that `fields()` and `exclude_fields()` works both for main models
(on normal queries like `get`, `all` etc.)
as well as `select_related` and `prefetch_related` models
(with nested notation).
Mandatory fields cannot be excluded as it will raise `ValidationError`,
to exclude a field it has to be nullable.
Pk column cannot be excluded - it's always auto added even
if explicitly excluded.
Actual call delegated to QuerySet.
**Arguments**:
- `columns (Union[List, str, Set, Dict])`: columns to exclude
**Returns**:
`(QuerysetProxy)`: QuerysetProxy
<a name="relations.querysetproxy.QuerysetProxy.order_by"></a>
#### order\_by
```python
| order_by(columns: Union[List, str]) -> "QuerysetProxy"
```
With `order_by()` you can order the results from database based on your
choice of fields.
You can provide a string with field name or list of strings with fields names.
Ordering in sql will be applied in order of names you provide in order_by.
By default if you do not provide ordering `ormar` explicitly orders by
all primary keys
If you are sorting by nested models that causes that the result rows are
unsorted by the main model `ormar` will combine those children rows into
one main model.
The main model will never duplicate in the result
To order by main model field just provide a field name
To sort on nested models separate field names with dunder '__'.
You can sort this way across all relation types -> `ForeignKey`,
reverse virtual FK and `ManyToMany` fields.
To sort in descending order provide a hyphen in front of the field name
Actual call delegated to QuerySet.
**Arguments**:
- `columns (Union[List, str])`: columns by which models should be sorted
**Returns**:
`(QuerysetProxy)`: QuerysetProxy

159
docs/api/relations/relation-manager.md Normal file
View File

@ -0,0 +1,159 @@
<a name="relations.relation_manager"></a>
# relations.relation\_manager
<a name="relations.relation_manager.RelationsManager"></a>
## RelationsManager Objects
```python
class RelationsManager()
```
Manages relations on a Model, each Model has it's own instance.
<a name="relations.relation_manager.RelationsManager.__init__"></a>
#### \_\_init\_\_
```python
| __init__(related_fields: List[Type[ForeignKeyField]] = None, owner: "NewBaseModel" = None) -> None
```
<a name="relations.relation_manager.RelationsManager._get_relation_type"></a>
#### \_get\_relation\_type
```python
| _get_relation_type(field: Type[BaseField]) -> RelationType
```
Returns type of the relation declared on a field.
**Arguments**:
- `field (Type[BaseField])`: field with relation declaration
**Returns**:
`(RelationType)`: type of the relation defined on field
<a name="relations.relation_manager.RelationsManager._add_relation"></a>
#### \_add\_relation
```python
| _add_relation(field: Type[BaseField]) -> None
```
Registers relation in the manager.
Adds Relation instance under field.name.
**Arguments**:
- `field (Type[BaseField])`: field with relation declaration
<a name="relations.relation_manager.RelationsManager.__contains__"></a>
#### \_\_contains\_\_
```python
| __contains__(item: str) -> bool
```
Checks if relation with given name is already registered.
**Arguments**:
- `item (str)`: name of attribute
**Returns**:
`(bool)`: result of the check
<a name="relations.relation_manager.RelationsManager.get"></a>
#### get
```python
| get(name: str) -> Optional[Union["T", Sequence["T"]]]
```
Returns the related model/models if relation is set.
Actual call is delegated to Relation instance registered under relation name.
**Arguments**:
- `name (str)`: name of the relation
**Returns**:
`(Optional[Union[Model, List[Model]])`: related model or list of related models if set
<a name="relations.relation_manager.RelationsManager._get"></a>
#### \_get
```python
| _get(name: str) -> Optional[Relation]
```
Returns the actual relation and not the related model(s).
**Arguments**:
- `name (str)`: name of the relation
**Returns**:
`(ormar.relations.relation.Relation)`: Relation instance
<a name="relations.relation_manager.RelationsManager.add"></a>
#### add
```python
| @staticmethod
| add(parent: "Model", child: "Model", child_name: str, virtual: bool, relation_name: str) -> None
```
Adds relation on both sides -> meaning on both child and parent models.
One side of the relation is always weakref proxy to avoid circular refs.
Based on the side from which relation is added and relation name actual names
of parent and child relations are established. The related models are registered
on both ends.
**Arguments**:
- `parent (Model)`: parent model on which relation should be registered
- `child (Model)`: child model to register
- `child_name (str)`: potential child name used if related name is not set
- `virtual (bool)`:
- `relation_name (str)`: name of the relation
<a name="relations.relation_manager.RelationsManager.remove"></a>
#### remove
```python
| remove(name: str, child: Union["NewBaseModel", Type["NewBaseModel"]]) -> None
```
Removes given child from relation with given name.
Since you can have many relations between two models you need to pass a name
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
<a name="relations.relation_manager.RelationsManager.remove_parent"></a>
#### remove\_parent
```python
| @staticmethod
| remove_parent(item: Union["NewBaseModel", Type["NewBaseModel"]], parent: "Model", name: str) -> None
```
Removes given parent from relation with given name.
Since you can have many relations between two models you need to pass a name
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

151
docs/api/relations/relation-proxy.md Normal file
View File

@ -0,0 +1,151 @@
<a name="relations.relation_proxy"></a>
# relations.relation\_proxy
<a name="relations.relation_proxy.RelationProxy"></a>
## RelationProxy Objects
```python
class RelationProxy(list)
```
Proxy of the Relation that is a list with special methods.
<a name="relations.relation_proxy.RelationProxy.__init__"></a>
#### \_\_init\_\_
```python
| __init__(relation: "Relation", type_: "RelationType", field_name: str, data_: Any = None) -> None
```
<a name="relations.relation_proxy.RelationProxy.related_field_name"></a>
#### related\_field\_name
```python
| @property
| related_field_name() -> str
```
On first access calculates the name of the related field, later stored in
_related_field_name property.
**Returns**:
`(str)`: name of the related field
<a name="relations.relation_proxy.RelationProxy.__getattribute__"></a>
#### \_\_getattribute\_\_
```python
| __getattribute__(item: str) -> Any
```
Since some QuerySetProxy methods overwrite builtin list methods we
catch calls to them and delegate it to QuerySetProxy instead.
**Arguments**:
- `item (str)`: name of attribute
**Returns**:
`(Any)`: value of attribute
<a name="relations.relation_proxy.RelationProxy.__getattr__"></a>
#### \_\_getattr\_\_
```python
| __getattr__(item: str) -> Any
```
Delegates calls for non existing attributes to QuerySetProxy.
**Arguments**:
- `item (str)`: name of attribute/method
**Returns**:
`(method)`: method from QuerySetProxy if exists
<a name="relations.relation_proxy.RelationProxy._initialize_queryset"></a>
#### \_initialize\_queryset
```python
| _initialize_queryset() -> None
```
Initializes the QuerySetProxy if not yet initialized.
<a name="relations.relation_proxy.RelationProxy._check_if_queryset_is_initialized"></a>
#### \_check\_if\_queryset\_is\_initialized
```python
| _check_if_queryset_is_initialized() -> bool
```
Checks if the QuerySetProxy is already set and ready.
**Returns**:
`(bool)`: result of the check
<a name="relations.relation_proxy.RelationProxy._check_if_model_saved"></a>
#### \_check\_if\_model\_saved
```python
| _check_if_model_saved() -> None
```
Verifies if the parent model of the relation has been already saved.
Otherwise QuerySetProxy cannot filter by parent primary key.
<a name="relations.relation_proxy.RelationProxy._set_queryset"></a>
#### \_set\_queryset
```python
| _set_queryset() -> "QuerySet"
```
Creates new QuerySet with relation model and pre filters it with currents
parent model primary key, so all queries by definition are already related
to the parent model only, without need for user to filter them.
**Returns**:
`(QuerySet)`: initialized QuerySet
<a name="relations.relation_proxy.RelationProxy.remove"></a>
#### remove
```python
| async remove(item: "Model", keep_reversed: bool = True) -> None
```
Removes the item from relation with parent.
Through models are automatically deleted for m2m relations.
For reverse FK relations keep_reversed flag marks if the reversed models
should be kept or deleted from the database too (False means that models
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
<a name="relations.relation_proxy.RelationProxy.add"></a>
#### add
```python
| async add(item: "Model") -> None
```
Adds child model to relation.
For ManyToMany relations through instance is automatically created.
**Arguments**:
- `item (Model)`: child to add to relation

128
docs/api/relations/relation.md Normal file
View File

@ -0,0 +1,128 @@
<a name="relations.relation"></a>
# relations.relation
<a name="relations.relation.RelationType"></a>
## RelationType Objects
```python
class RelationType(Enum)
```
Different types of relations supported by ormar:
* ForeignKey = PRIMARY
* reverse ForeignKey = REVERSE
* ManyToMany = MULTIPLE
<a name="relations.relation.RelationType.PRIMARY"></a>
#### PRIMARY
<a name="relations.relation.RelationType.REVERSE"></a>
#### REVERSE
<a name="relations.relation.RelationType.MULTIPLE"></a>
#### MULTIPLE
<a name="relations.relation.Relation"></a>
## Relation Objects
```python
class Relation()
```
Keeps related Models and handles adding/removing of the children.
<a name="relations.relation.Relation.__init__"></a>
#### \_\_init\_\_
```python
| __init__(manager: "RelationsManager", type_: RelationType, field_name: str, to: Type["T"], through: Type["T"] = None) -> None
```
Initialize the Relation and keep the related models either as instances of
passed Model, or as a RelationProxy which is basically a list of models with
some special behavior, as it exposes QuerySetProxy and allows querying the
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
<a name="relations.relation.Relation._clean_related"></a>
#### \_clean\_related
```python
| _clean_related() -> None
```
Removes dead weakrefs from RelationProxy.
<a name="relations.relation.Relation._find_existing"></a>
#### \_find\_existing
```python
| _find_existing(child: Union["NewBaseModel", Type["NewBaseModel"]]) -> Optional[int]
```
Find child model in RelationProxy if exists.
**Arguments**:
- `child (Model)`: child model to find
**Returns**:
`(Optional[ind])`: index of child in RelationProxy
<a name="relations.relation.Relation.add"></a>
#### add
```python
| add(child: "T") -> None
```
Adds child Model to relation, either sets child as related model or adds
it to the list in RelationProxy depending on relation type.
**Arguments**:
- `child (Model)`: model to add to relation
<a name="relations.relation.Relation.remove"></a>
#### remove
```python
| remove(child: Union["NewBaseModel", Type["NewBaseModel"]]) -> None
```
Removes child Model from relation, either sets None as related model or removes
it from the list in RelationProxy depending on relation type.
**Arguments**:
- `child (Model)`: model to remove from relation
<a name="relations.relation.Relation.get"></a>
#### get
```python
| get() -> Optional[Union[List["T"], "T"]]
```
Return the related model or models from RelationProxy.
**Returns**:
`(Optional[Union[List[Model], Model]])`: related model/models if set
<a name="relations.relation.Relation.__repr__"></a>
#### \_\_repr\_\_
```python
| __repr__() -> str
```

26
docs/api/relations/utils.md Normal file
View File

@ -0,0 +1,26 @@
<a name="relations.utils"></a>
# relations.utils
<a name="relations.utils.get_relations_sides_and_names"></a>
#### get\_relations\_sides\_and\_names
```python
get_relations_sides_and_names(to_field: Type[BaseField], parent: "Model", child: "Model", child_name: str, virtual: bool, relation_name: str) -> Tuple["Model", "Model", str, str]
```
Determines the names of child and parent relations names, as well as
changes one of the sides of the relation into weakref.proxy to model.
**Arguments**:
- `to_field (BaseField)`: field with relation definition
- `parent (Model)`: parent model
- `child (Model)`: child model
- `child_name (str)`: name of the child
- `virtual (bool)`: flag if relation is virtual
- `relation_name ()`:
**Returns**:
`(Tuple["Model", "Model", str, str])`: parent, child, child_name, to_name