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

update docs

Browse Source
This commit is contained in:
collerek
2020-12-22 13:10:48 +01:00
parent c8aad2385c
commit 63f7b0d572
7 changed files with 307 additions and 67 deletions
Download Patch File Download Diff File Expand all files Collapse all files

91
docs/fastapi.md
View File

@ -9,20 +9,46 @@ Here you can find a very simple sample application code.
!!!warning
This example assumes that you already have a database created. If that is not the case please visit [database initialization][database initialization] section.
!!!tip
The following example (all sections) should be put in one file.
It's divided into subsections for clarity.
## Imports and initialization
First take care of the imports and initialization
```python hl_lines="1-12"
--8<-- "../docs_src/fastapi/docs001.py"
```python
from typing import List, Optional
import databases
import sqlalchemy
from fastapi import FastAPI
import ormar
app = FastAPI()
metadata = sqlalchemy.MetaData()
database = databases.Database("sqlite:///test.db")
app.state.database = database
```
## Database connection
Next define startup and shutdown events (or use middleware)
- note that this is `databases` specific setting not the ormar one
```python hl_lines="15-26"
--8<-- "../docs_src/fastapi/docs001.py"
```python
@app.on_event("startup")
async def startup() -> None:
database_ = app.state.database
if not database_.is_connected:
await database_.connect()
@app.on_event("shutdown")
async def shutdown() -> None:
database_ = app.state.database
if database_.is_connected:
await database_.disconnect()
```
!!!info
@ -33,8 +59,27 @@ Next define startup and shutdown events (or use middleware)
Define ormar models with appropriate fields.
Those models will be used insted of pydantic ones.
```python hl_lines="29-47"
--8<-- "../docs_src/fastapi/docs001.py"
```python
class Category(ormar.Model):
class Meta:
tablename = "categories"
metadata = metadata
database = database
id: int = ormar.Integer(primary_key=True)
name: str = ormar.String(max_length=100)
class Item(ormar.Model):
class Meta:
tablename = "items"
metadata = metadata
database = database
id: int = ormar.Integer(primary_key=True)
name: str = ormar.String(max_length=100)
category: Optional[Category] = ormar.ForeignKey(Category, nullable=True)
```
!!!tip
@ -45,8 +90,38 @@ Those models will be used insted of pydantic ones.
Define your desired endpoints, note how `ormar` models are used both
as `response_model` and as a requests parameters.
```python hl_lines="50-79"
--8<-- "../docs_src/fastapi/docs001.py"
```python
@app.get("/items/", response_model=List[Item])
async def get_items():
items = await Item.objects.select_related("category").all()
return items
@app.post("/items/", response_model=Item)
async def create_item(item: Item):
await item.save()
return item
@app.post("/categories/", response_model=Category)
async def create_category(category: Category):
await category.save()
return category
@app.put("/items/{item_id}")
async def get_item(item_id: int, item: Item):
item_db = await Item.objects.get(pk=item_id)
return await item_db.update(**item.dict())
@app.delete("/items/{item_id}")
async def delete_item(item_id: int, item: Item = None):
if item:
return {"deleted_rows": await item.delete()}
item_db = await Item.objects.get(pk=item_id)
return {"deleted_rows": await item_db.delete()}
```
!!!note

220
docs/models/inheritance.md
View File

@ -9,15 +9,27 @@ Out of various types of ORM models inheritance `ormar` currently supports two of
The short summary of different types of inheritance is:
* **Mixins [SUPPORTED]** - don't subclass `ormar.Model`, just define fields that are later used on different models (like `created_date` and `updated_date` on each model), only actual models create tables, but those fields from mixins are added
* **Concrete table inheritance [SUPPORTED]** - means that parent is marked as abstract and each child has it's own table with columns from parent and own child columns, kind of similar to Mixins but parent also is a Model
* **Single table inheritance [NOT SUPPORTED]** - means that only one table is created with fields that are combination/sum of the parent and all children models but child models use only subset of column in db (all parent and own ones, skipping the other children ones)
* **Multi/ Joined table inheritance [NOT SUPPORTED]** - means that part of the columns is saved on parent model and part is saved on child model that are connected to each other by kind of one to one relation and under the hood you operate on two models at once
* **Proxy models [NOT SUPPORTED]** - means that only parent has an actual table, children just add methods, modify settings etc.
* **Mixins [SUPPORTED]** - don't subclass `ormar.Model`, just define fields that are
later used on different models (like `created_date` and `updated_date` on each model),
only actual models create tables, but those fields from mixins are added
* **Concrete table inheritance [SUPPORTED]** - means that parent is marked as abstract
and each child has it's own table with columns from parent and own child columns, kind
of similar to Mixins but parent also is a Model
* **Single table inheritance [NOT SUPPORTED]** - means that only one table is created
with fields that are combination/sum of the parent and all children models but child
models use only subset of column in db (all parent and own ones, skipping the other
children ones)
* **Multi/ Joined table inheritance [NOT SUPPORTED]** - means that part of the columns
is saved on parent model and part is saved on child model that are connected to each
other by kind of one to one relation and under the hood you operate on two models at
once
* **Proxy models [NOT SUPPORTED]** - means that only parent has an actual table,
children just add methods, modify settings etc.
## Mixins
To use Mixins just define a class that is not inheriting from an `ormar.Model` but is defining `ormar.Fields` as class variables.
To use Mixins just define a class that is not inheriting from an `ormar.Model` but is
defining `ormar.Fields` as class variables.
```python
# a mixin defines the fields but is a normal python class
@ -25,6 +37,7 @@ class AuditMixin:
created_by: str = ormar.String(max_length=100)
updated_by: str = ormar.String(max_length=100, default="Sam")
class DateFieldsMixins:
created_date: datetime.datetime = ormar.DateTime(default=datetime.datetime.now)
updated_date: datetime.datetime = ormar.DateTime(default=datetime.datetime.now)
@ -42,36 +55,37 @@ class Category(ormar.Model, DateFieldsMixins, AuditMixin):
code: int = ormar.Integer()
```
!!!note
Note that Mixins are **not** models, so you still need to inherit from `ormar.Model` as well as define `Meta` class in the final model.
!!!tip
Note that Mixins are **not** models, so you still need to inherit
from `ormar.Model` as well as define `Meta` class in the **final** model.
A Category class above will have four additional fields: `created_date`, `updated_date`, `created_by` and `updated_by`.
A Category class above will have four additional fields: `created_date`, `updated_date`,
`created_by` and `updated_by`.
There will be only one table created for model Category, with `Category` class fields combined with all `Mixins` fields.
There will be only one table created for model `Category` (`categories`), with `Category` class fields
combined with all `Mixins` fields.
Note that Mixin in class name is optional but is a good python practice.
!!!warning
You cannot declare a field in a `Model` that is already defined in one of the `Mixins` you inherit from.
So in example above `Category` cannot declare it's own `created_date` as this filed will be inherited from `DateFieldsMixins`.
If you try to the `ModelDefinitionError` will be raised.
Note that `Mixin` in class name is optional but is a good python practice.
## Concrete table inheritance
In concept concrete table inheritance is very similar to Mixins, but uses actual `ormar.Models` as base classes.
In concept concrete table inheritance is very similar to Mixins, but uses
actual `ormar.Models` as base classes.
!!!warning
Note that base classes have `abstract=True` set in `Meta` class, if you try to inherit from non abstract marked class `ModelDefinitionError` will be raised.
!!!warning
Note that base classes have `abstract=True` set in `Meta` class, if you try
to inherit from non abstract marked class `ModelDefinitionError` will be raised.
Since this abstract Model will never be initialized you can skip `metadata` and `database` in it's `Meta` definition.
Since this abstract Model will never be initialized you can skip `metadata`
and `database` in it's `Meta` definition.
But if you provide it - it will be inherited, that way you do not have to provide `metadata` and `databases` in concrete class
But if you provide it - it will be inherited, that way you do not have to
provide `metadata` and `databases` in the final/concrete class
Note that you can always overwrite it in child/concrete class if you need to.
Note that you can always overwrite it in child/concrete class if you need to.
More over at least one of the classes in inheritance chain have to provide it - otherwise an error will be raised.
More over at least one of the classes in inheritance chain have to provide both `database` and `metadata` -
otherwise an error will be raised.
```python
# note that base classes have abstract=True
@ -83,6 +97,7 @@ class AuditModel(ormar.Model):
created_by: str = ormar.String(max_length=100)
updated_by: str = ormar.String(max_length=100, default="Sam")
# but if you provide it it will be inherited - DRY (Don't Repeat Yourself) in action
class DateFieldsModel(ormar.Model):
class Meta:
@ -105,24 +120,25 @@ class Category(DateFieldsModel, AuditModel):
```
The list of inherited options/settings is as follows: `metadata`, `database` and `constraints`.
The list of inherited options/settings is as follows: `metadata`, `database`
and `constraints`.
Also methods decorated with `@property_field` decorator will be inherited/recognized.
Of course apart from that all fields from base classes are combined and created in the concrete table of the final Model.
Of course apart from that all fields from base classes are combined and created in the
concrete table of the final Model.
!!!warning
You cannot declare a field in a `Model` that is already defined in one of the `Mixins` you inherit from.
So in example above `Category` cannot declare it's own `created_date` as this filed will be inherited from `DateFieldsMixins`.
If you try to the `ModelDefinitionError` will be raised.
!!!tip
Note how you don't have to provide `abstarct=False` in the final class - it's the default setting
that is not inherited.
## Redefining fields in subclasses
Note that you can redefine previously created fields like in normal python class inheritance.
Note that you can redefine previously created fields like in normal python class
inheritance.
Whenever you define a field with same name and new definition it will completely replace the previously defined one.
Whenever you define a field with same name and new definition it will completely replace
the previously defined one.
```python
# base class
@ -131,7 +147,7 @@ class DateFieldsModel(ormar.Model):
abstract = True
metadata = metadata
database = db
# note that UniqueColumns need sqlalchemy db columns names not the ormar one
# note that UniqueColumns need sqlalchemy db columns names not the ormar ones
constraints = [ormar.UniqueColumns("creation_date", "modification_date")]
created_date: datetime.datetime = ormar.DateTime(
@ -141,6 +157,7 @@ class DateFieldsModel(ormar.Model):
default=datetime.datetime.now, name="modification_date"
)
class RedefinedField(DateFieldsModel):
class Meta(ormar.ModelMeta):
tablename = "redefines"
@ -151,7 +168,7 @@ class RedefinedField(DateFieldsModel):
# here the created_date is replaced by the String field
created_date: str = ormar.String(max_length=200, name="creation_date")
# you can verify that the final field is correctly declared and created
changed_field = RedefinedField.Meta.model_fields["created_date"]
assert changed_field.default is None
@ -163,10 +180,10 @@ assert isinstance(
)
```
!!!warning
!!!warning
If you declare `UniqueColumns` constraint with column names, the final model **has to have**
a column with the same name declared. Otherwise, the `ModelDefinitionError` will be raised.
So in example above if you do not provide `name` for `created_date` in `RedefinedField` model
ormar will complain.
@ -174,12 +191,129 @@ assert isinstance(
`created_date: str = ormar.String(max_length=200, name="creation_date2") # exception`
## Relations in inheritance
You can declare relations in every step of inheritance, so both in parent and child classes.
You can declare relations in every step of inheritance, so both in parent and child
classes.
But you always need to be aware of related_name parameter, that has to be unique across a model,
when you define multiple child classes that inherit the same relation.
When inheriting relations, you always need to be aware of `related_name` parameter, that
has to be unique across a model, when you define multiple child classes that inherit the
same relation.
If you do not provide `related_name` parameter ormar calculates it for you. This works
with inheritance as all child models have to have different class names, which are used
to calculate the default `related_name` (class.name.lower()+'s').
But, if you provide a `related_name` this name cannot be reused in all child models as
they would overwrite each other on the related model side.
Therefore, you have two options:
* redefine relation field in child models and manually provide different `related_name`
parameters
* let this for `ormar` to handle -> auto adjusted related_name are: original
related_name + "_" + child model **table** name
That might sound complicated but let's look at the following example:
```python
# normal model used in relation
class Person(ormar.Model):
class Meta:
metadata = metadata
database = db
id: int = ormar.Integer(primary_key=True)
name: str = ormar.String(max_length=100)
# parent model - needs to be abstract
class Car(ormar.Model):
class Meta:
abstract = True
metadata = metadata
database = db
id: int = ormar.Integer(primary_key=True)
name: str = ormar.String(max_length=50)
owner: Person = ormar.ForeignKey(Person)
# note that we refer to the Person model again so we **have to** provide related_name
co_owner: Person = ormar.ForeignKey(Person, related_name="coowned")
created_date: datetime.datetime = ormar.DateTime(default=datetime.datetime.now)
class Truck(Car):
class Meta:
pass
max_capacity: int = ormar.Integer()
class Bus(Car):
class Meta:
# default naming is name.lower()+'s' so it's ugly for buss ;)
tablename = "buses"
max_persons: int = ormar.Integer()
```
Now when you will inspect the fields on Person model you will get:
```python
Person.Meta.model_fields
"""
{'id': <class 'ormar.fields.model_fields.Integer'>,
'name': <class 'ormar.fields.model_fields.String'>,
'trucks': <class 'ormar.fields.foreign_key.ForeignKey'>,
'coowned_trucks': <class 'ormar.fields.foreign_key.ForeignKey'>,
'buss': <class 'ormar.fields.foreign_key.ForeignKey'>,
'coowned_buses': <class 'ormar.fields.foreign_key.ForeignKey'>}
"""
```
Note how you have `trucks` and `buss` fields that leads to Truck and Bus class that
this Person owns. There were no `related_name` parameter so default names were used.
At the same time the co-owned cars need to be referenced by `coowned_trucks`
and `coowned_buses`. Ormar appended `_trucks` and `_buses` suffixes taken from child
model table names.
Seems fine, but the default name for owned trucks is ok (`trucks`) but the `buss` is
ugly, so how can we change it?
The solution is pretty simple - just redefine the field in Bus class and provide
different `related_name` parameter.
```python
# rest of the above example remains the same
class Bus(Car):
class Meta:
tablename = "buses"
# new field that changes the related_name
owner: Person = ormar.ForeignKey(Person, related_name="buses")
max_persons: int = ormar.Integer()
```
Now the columns looks much better.
```python
Person.Meta.model_fields
"""
{'id': <class 'ormar.fields.model_fields.Integer'>,
'name': <class 'ormar.fields.model_fields.String'>,
'trucks': <class 'ormar.fields.foreign_key.ForeignKey'>,
'coowned_trucks': <class 'ormar.fields.foreign_key.ForeignKey'>,
'buses': <class 'ormar.fields.foreign_key.ForeignKey'>,
'coowned_buses': <class 'ormar.fields.foreign_key.ForeignKey'>}
"""
```
!!!note
You could also provide `related_name` for the `owner` field, that way the proper suffixes
would be added.
`owner: Person = ormar.ForeignKey(Person, related_name="owned")`
and model fields for Person owned cars would become `owned_trucks` and `owned_buses`.

6
docs/relations/foreign-key.md
View File

@ -112,7 +112,11 @@ But you can overwrite this name by providing `related_name` parameter like below
!!!tip
The reverse relation on access returns list of `wekref.proxy` to avoid circular references.
!!!warning
When you provide multiple relations to the same model `ormar` can no longer auto generate
the `related_name` for you. Therefore, in that situation you **have to** provide `related_name`
for all but one (one can be default and generated) or all related fields.
## Relation Setup

18
docs/relations/many-to-many.md
View File

@ -9,7 +9,7 @@ Sqlalchemy column and Type are automatically taken from target `Model`.
## Defining Models
```Python
```Python hl_lines="32 49-50"
--8<-- "../docs_src/relations/docs002.py"
```
@ -60,6 +60,22 @@ Reverse relation exposes QuerysetProxy API that allows you to query related mode
To read which methods of QuerySet are available read below [querysetproxy][querysetproxy]
## related_name
By default, the related_name is generated in the same way as for the `ForeignKey` relation (class.name.lower()+'s'),
but in the same way you can overwrite this name by providing `related_name` parameter like below:
```Python
categories: Optional[Union[Category, List[Category]]] = ormar.ManyToMany(
Category, through=PostCategory, related_name="new_categories"
)
```
!!!warning
When you provide multiple relations to the same model `ormar` can no longer auto generate
the `related_name` for you. Therefore, in that situation you **have to** provide `related_name`
for all but one (one can be default and generated) or all related fields.
[queries]: ./queries.md
[querysetproxy]: ./queryset-proxy.md

34
docs/releases.md
View File

@ -1,18 +1,30 @@
# 0.8.0
* **Breaking:** removing parent from child side in reverse ForeignKey relation now requires passing a relation `name`,
as the same model can be registered multiple times and ormar needs to know from which relation on the parent you want to remove the child.
* **Breaking:** applying limit and offset with select related is by default applied only on the main table before the join -> meaning that not the total
number of rows is limited but just main models (first one in the query, the one to used to construct it)
* **Breaking:** issuing `first()` now fetches the first row ordered by the primary key asc (so first one inserted (can be different for non number primary keys - i.e. alphabetical order of string)) and also can be used with `prefetch_related`
## Breaking
* **Breaking:** `remove()` parent from child side in reverse ForeignKey relation now requires passing a relation `name`,
as the same model can be registered multiple times and `ormar` needs to know from which relation on the parent you want to remove the child.
* **Breaking:** applying `limit` and `offset` with `select_related` is by default applied only on the main table before the join -> meaning that not the total
number of rows is limited but just main models (first one in the query, the one to used to construct it). Yu can still limit all rows from db response with `limit_raw_sql=True` flag on either `limit` or `offset` (or both)
* **Breaking:** issuing `first()` now fetches the first row ordered by the primary key asc (so first one inserted (can be different for non number primary keys - i.e. alphabetical order of string))
* **Breaking:** issuing `get()` **without any filters** now fetches the first row ordered by the primary key desc (so should be last one inserted (can be different for non number primary keys - i.e. alphabetical order of string))
* Introduce inheritance, for now two types of inheritance are possible:
* **Mixins** - don't subclass `ormar.Model`, just define fields that are later used on different models (like `created_date` and `updated_date` on each model), only actual models create tables, but those fields from mixins are added
* **Concrete table inheritance** - means that parent is marked as abstract and each child has its own table with columns from the parent and own child columns, kind of similar to Mixins but parent also is a Model
* To read more check the docs on models -> inheritance section.
* Fix bug in order_by for primary model order bys
## Features
* Introduce **inheritance**, for now two types of inheritance are possible:
* **Mixins** - don't subclass `ormar.Model`, just define fields that are later used on different models (like `created_date` and `updated_date` on each child model), only actual models create tables, but those fields from mixins are added
* **Concrete table inheritance** - means that parent is marked as `abstract=True` in Meta class and each child has its own table with columns from the parent and own child columns, kind of similar to Mixins but parent also is a (an abstract) Model
* To read more check the docs on models -> inheritance section.
* QuerySet `first()` can be used with `prefetch_related`
## Fixes
* Fix minor bug in `order_by` for primary model order bys
* Fix in `prefetch_query` for multiple related_names for the same model.
* Split and cleanup in docs.
## Docs
* Split and cleanup in docs:
* Divide models section into subsections
* Divide relations section into subsections
* Divide fields section into subsections
* Add model inheritance section
# 0.7.5

2
mkdocs.yml
View File

@ -10,8 +10,8 @@ nav:
- Migrations: models/migrations.md
- Internals: models/internals.md
- Fields:
- Fields types: fields/field-types.md
- Common parameters: fields/common-parameters.md
- Fields types: fields/field-types.md
- Relations:
- relations/index.md
- relations/foreign-key.md

3
tests/test_inheritance_concrete.py
View File

@ -107,8 +107,7 @@ class Car(ormar.Model):
class Truck(Car):
class Meta:
metadata = metadata
database = db
pass
max_capacity: int = ormar.Integer()