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

expand docs on get_pydantic

Browse Source
This commit is contained in:
collerek
2021-05-31 19:04:01 +02:00
parent 5cbac6583e
commit 64e4288358
9 changed files with 330 additions and 35 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
docs/fastapi/index.md
View File

@ -1,3 +1,4 @@
# Fastapi
The use of ormar with fastapi is quite simple.
@ -14,8 +15,15 @@ Here you can find a very simple sample application code.
It's divided into subsections for clarity.
!!!note
If you want to read more on how you can use ormar models in fastapi requests and
responses check the [responses](response.md) and [requests](requests.md) documentation.
## Quick Start
!!!note
Note that you can find the full quick start script in the [github](https://github.com/collerek/ormar) repo under examples.
### Imports and initialization
First take care of the imports and initialization
@ -210,6 +218,6 @@ def test_all_endpoints():
You can read more on testing fastapi in [fastapi][fastapi] docs.
[fastapi]: https://fastapi.tiangolo.com/
[models]: ./models/index.md
[database initialization]: ./models/migrations.md
[models]: ../models/index.md
[database initialization]: ../models/migrations.md
[tests]: https://github.com/collerek/ormar/tree/master/tests

157
docs/fastapi/requests.md
View File

@ -1,42 +1,143 @@
# Request
Note that the same (need for additional) applies if you want to pass less fields as request parameters but keep them as required on ormar.Model. This is more rare situation, cause it means that you will get the fields value from somewhere else than request (as you not pass them).
You can use ormar Models in `fastapi` request `Body` parameters instead of pydantic models.
That usually means that you can pass server_default to ormar Fields and that will fill the value in sql, or you can use default ormar Fields parameter and pass either static value or a function (with no args) that will fill this field for you. If you pass default or server_default ormar/pydantic field becomes optional and you can use the same model in request and ormar.
You can of course also mix `ormar.Model`s with `pydantic` ones if you need to.
In sample below only last_name is required
One of the most common tasks in requests is excluding certain fields that you do not want to include in the payload you send to API.
This can be achieved in several ways in `ormar` so below you can review your options and select the one most suitable for your situation.
## Excluding fields in request
### Optional fields
Note that each field that is optional is not required, that means that Optional fields can be skipped both in response and in requests.
Field is not required if (any/many/all) of following:
* Field is marked with `nullable=True`
* Field has `default` value or function provided, i.e. `default="Test"`
* Field has a `server_default` value set
* Field is an `autoincrement=True` `primary_key` field (note that `ormar.Integer` `primary_key` is `autoincrement` by default)
Example:
```python
def gen_pass():
choices = string.ascii_letters + string.digits + "!@#$%^&*()".split()
return "".join(random.choice(choices) for _ in range(20))
class RandomModel(ormar.Model):
class User(ormar.Model):
class Meta:
tablename: str = "users"
metadata = metadata
database = database
id: int = ormar.Integer(primary_key=True)
password: str = ormar.String(max_length=255, default=gen_pass)
first_name: str = ormar.String(max_length=255, default='John')
# note that in ormar by default if you not provide autoincrement, default or server_default the field is required
# so nullable=False - you do not need to provide it for each field
email: str = ormar.String(max_length=255)
password: str = ormar.String(max_length=255)
first_name: str = ormar.String(max_length=255, nullable=True)
last_name: str = ormar.String(max_length=255)
created_date: str = ormar.DateTime(server_default=sqlalchemy.func.now())
# that way only last_name is required and you will get "random" password etc.
# so you can still use ormar model in Request param.
@app.post("/random/", response_model=RandomModel)
async def create_user5(user: RandomModel):
return await user.save()
# you can pass only last_name in payload but still get the data persisted in db
user3 = {
'last_name': 'Test'
}
response = client.post("/random/", json=user3)
assert list(response.json().keys()) == ['id', 'password', 'first_name', 'last_name', 'created_date']
category: str = ormar.String(max_length=255, default="User")
```
But if you cannot set default you will need additional pydantic Model.
In above example fields `id` (is an `autoincrement` `Integer`), `first_name` ( has `nullable=True`) and `category` (has `default`) are optional and can be skipped in response and model wil still validate.
If the field is nullable you don't have to include it in payload during creation as well as in response, so given example above you can:
!!!Warning
Note that although you do not have to pass the optional field, you still **can** do it.
And if someone will pass a value it will be used later unless you take measures to prevent it.
```python
# note that app is an FastApi app
@app.post("/users/", response_model=User) # here we use ormar.Model in response
async def create_user(user: User): # here we use ormar.Model in request parameter
return await user.save()
```
That means that if you do not pass i.e. `first_name` in request it will validate correctly (as field is optional), `None` will be saved in the database.
### Generate `pydantic` model from `ormar.Model`
Since task of excluding fields is so common `ormar` has a special way to generate `pydantic` models from existing `ormar.Models` without you needing to retype all the fields.
That method is `get_pydantic()` method available on all models classes.
```python
# generate a tree of models without password on User and without priority on nested Category
RequestUser = User.get_pydantic(exclude={"password": ..., "category": {"priority"}})
@app.post("/users3/", response_model=User) # here you can also use both ormar/pydantic
async def create_user3(user: RequestUser): # use the generated model here
# note how now user is pydantic and not ormar Model so you need to convert
return await User(**user.dict()).save()
```
!!!Note
To see more examples and read more visit [get_pydantic](../models/methods.md#get_pydantic) part of the documentation.
!!!Warning
The `get_pydantic` method generates all models in a tree of nested models according to an algorithm that allows to avoid loops in models (same algorithm that is used in `dict()`, `select_all()` etc.)
That means that nested models won't have reference to parent model (by default ormar relation is biderectional).
Note also that if given model exists in a tree more than once it will be doubled in pydantic models (each occurance will have separate own model). That way you can exclude/include different fields on different leafs of the tree.
#### Mypy and type checking
Note that assigning a function as a python type passes at runtime (as it's not checked) the static type checkers like mypy will complain.
Although result of the function call will always be the same for given model using a dynamically created type is not allowed.
Therefore you have two options:
First one is to simply add `# type: ignore` to skip the type checking
```python
RequestUser = User.get_pydantic(exclude={"password": ..., "category": {"priority"}})
@app.post("/users3/", response_model=User)
async def create_user3(user: RequestUser): # type: ignore
# note how now user is not ormar Model so you need to convert
return await User(**user.dict()).save()
```
The second one is a little bit more hacky and utilizes a way in which fastapi extract function parameters.
You can overwrite the `__annotations__` entry for given param.
```python
RequestUser = User.get_pydantic(exclude={"password": ..., "category": {"priority"}})
# do not use the app decorator
async def create_user3(user: User): # use ormar model here
return await User(**user.dict()).save()
# overwrite the function annotations entry for user param with generated model
create_user3.__annotations__["user"] = RequestUser
# manually call app functions (app.get, app.post etc.) and pass your function reference
app.post("/categories/", response_model=User)(create_user3)
```
Note that this will cause mypy to "think" that user is an ormar model but since in request it doesn't matter that much (you pass jsonized dict anyway and you need to convert before saving).
That still should work fine as generated model will be a subset of fields, so all needed fields will validate, and all not used fields will fail at runtime.
### Separate `pydantic` model
The final solution is to just create separate pydantic model manually.
That works exactly the same as with normal fastapi application, so you can have different models for response and requests etc.
Sample:
```python
import pydantic
class UserCreate(pydantic.BaseModel):
class Config:
orm_mode = True
email: str
first_name: str
last_name: str
password: str
@app.post("/users3/", response_model=User) # use ormar model here (but of course you CAN use pydantic also here)
async def create_user3(user: UserCreate): # use pydantic model here
# note how now request param is a pydantic model and not the ormar one
# so you need to parse/convert it to ormar before you can use database
return await User(**user.dict()).save()
```

17
docs/fastapi/response.md
View File

@ -212,9 +212,22 @@ async def create_user3(user: User):
!!!Note
To see more examples and read more visit [get_pydantic](../models/methods.md#get_pydantic) part of the documentation.
!!!Warning
The `get_pydantic` method generates all models in a tree of nested models according to an algorithm that allows to avoid loops in models (same algorithm that is used in `dict()`, `select_all()` etc.)
That means that nested models won't have reference to parent model (by default ormar relation is biderectional).
Note also that if given model exists in a tree more than once it will be doubled in pydantic models (each occurance will have separate own model). That way you can exclude/include different fields on different leafs of the tree.
### Separate `pydantic` model
The final solution is to just create separate pydantic model manually.
That works exactly the same as with normal fastapi application so you can have different models for response and requests etc.
Sample:
```python
import pydantic
class UserBase(pydantic.BaseModel):
class Config:
orm_mode = True
@ -223,8 +236,8 @@ class UserBase(pydantic.BaseModel):
first_name: str
last_name: str
# note that it's now can use ormar Model User2 with required password
@app.post("/users3/", response_model=UserBase) # use pydantic model here
async def create_user3(user: User): #use ormar model here
async def create_user3(user: User): #use ormar model here (but of course you CAN use pydantic also here)
return await user.save()
```

68
docs/models/methods.md
View File

@ -299,6 +299,74 @@ That means that this way you can effortlessly create pydantic models for request
!!!Note
To read more about possible excludes/includes and how to structure your exclude dictionary or set visit [fields](../queries/select-columns.md#fields) section of documentation
Given sample ormar models like follows:
```python
metadata = sqlalchemy.MetaData()
database = databases.Database(DATABASE_URL, force_rollback=True)
class BaseMeta(ormar.ModelMeta):
metadata = metadata
database = database
class Category(ormar.Model):
class Meta(BaseMeta):
tablename = "categories"
id: int = ormar.Integer(primary_key=True)
name: str = ormar.String(max_length=100)
class Item(ormar.Model):
class Meta(BaseMeta):
pass
id: int = ormar.Integer(primary_key=True)
name: str = ormar.String(max_length=100, default="test")
category: Optional[Category] = ormar.ForeignKey(Category, nullable=True)
```
You can generate pydantic models out of it with a one simple call.
```python
PydanticCategory = Category.get_pydantic(include={"id", "name"}
```
Which will generate model equivalent of:
```python
class Category(BaseModel):
id: Optional[int]
name: Optional[str] = "test"
```
!!!warning
Note that it's not a good practice to have several classes with same name in one module, as well as it would break `fastapi` docs.
Thats's why ormar adds random 3 uppercase letters to the class name. In example above it means that in reality class would be named i.e. `Category_XIP(BaseModel)`.
To exclude or include nested fields you can use dict or double underscores.
```python
# both calls are equivalent
PydanticCategory = Category.get_pydantic(include={"id", "items__id"})
PydanticCategory = Category.get_pydantic(include={"id": ..., "items": {"id"}})
```
and results in a generated structure as follows:
```python
class Item(BaseModel):
id: Optional[int]
class Category(BaseModel):
id: Optional[int]
items: Optional[List[Item]]
```
Of course you can use also deeply nested structures and ormar will generate it pydantic equivalent you (in a way that exclude loops).
Note how `Item` model above does not have a reference to `Category` although in ormar the relation is bidirectional (and `ormar.Item` has `categories` field).
## load
By default when you query a table without prefetching related models, the ormar will still construct

10
docs/releases.md
View File

@ -1,3 +1,13 @@
# 0.10.10
## ✨ Features
* Add `get_pydantic` flag that allows you to auto generate equivalent pydantic models tree from ormar.Model. This newly generated model tree can be used in requests and responses to exclude fields you do not want to include in the data.
## 💬 Other
* Expand fastapi part of the documentation to show samples of using ormar in requests and responses in fastapi.
# 0.10.9
## Important security fix