wip work on expanding fastapi docs
This commit is contained in:
collerek
215
docs/fastapi/index.md
Normal file
215
docs/fastapi/index.md
Normal file
@ -0,0 +1,215 @@
|
||||
|
||||
The use of ormar with fastapi is quite simple.
|
||||
|
||||
Apart from connecting to databases at startup everything else
|
||||
you need to do is substitute pydantic models with ormar models.
|
||||
|
||||
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.
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Imports and initialization
|
||||
|
||||
First take care of the imports and initialization
|
||||
```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
|
||||
@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
|
||||
You can read more on connecting to databases in [fastapi][fastapi] documentation
|
||||
|
||||
### Models definition
|
||||
|
||||
Define ormar models with appropriate fields.
|
||||
|
||||
Those models will be used instead of pydantic ones.
|
||||
|
||||
```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
|
||||
You can read more on defining `Models` in [models][models] section.
|
||||
|
||||
### Fastapi endpoints definition
|
||||
|
||||
Define your desired endpoints, note how `ormar` models are used both
|
||||
as `response_model` and as a requests parameters.
|
||||
|
||||
```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
|
||||
Note how ormar `Model` methods like save() are available straight out of the box after fastapi initializes it for you.
|
||||
|
||||
!!!note
|
||||
Note that you can return a `Model` (or list of `Models`) directly - fastapi will jsonize it for you
|
||||
|
||||
### Test the application
|
||||
|
||||
#### Run fastapi
|
||||
|
||||
If you want to run this script and play with fastapi swagger install uvicorn first
|
||||
|
||||
`pip install uvicorn`
|
||||
|
||||
And launch the fastapi.
|
||||
|
||||
`uvicorn <filename_without_extension>:app --reload`
|
||||
|
||||
Now you can navigate to your browser (by default fastapi address is `127.0.0.1:8000/docs`) and play with the api.
|
||||
|
||||
!!!info
|
||||
You can read more about running fastapi in [fastapi][fastapi] docs.
|
||||
|
||||
#### Test with pytest
|
||||
|
||||
Here you have a sample test that will prove that everything works as intended.
|
||||
|
||||
Be sure to create the tables first. If you are using pytest you can use a fixture.
|
||||
|
||||
```python
|
||||
@pytest.fixture(autouse=True, scope="module")
|
||||
def create_test_database():
|
||||
engine = sqlalchemy.create_engine(DATABASE_URL)
|
||||
metadata.create_all(engine)
|
||||
yield
|
||||
metadata.drop_all(engine)
|
||||
```
|
||||
|
||||
```python
|
||||
|
||||
# here is a sample test to check the working of the ormar with fastapi
|
||||
|
||||
from starlette.testclient import TestClient
|
||||
|
||||
def test_all_endpoints():
|
||||
# note that TestClient is only sync, don't use asyns here
|
||||
client = TestClient(app)
|
||||
# note that you need to connect to database manually
|
||||
# or use client as contextmanager during tests
|
||||
with client as client:
|
||||
response = client.post("/categories/", json={"name": "test cat"})
|
||||
category = response.json()
|
||||
response = client.post(
|
||||
"/items/", json={"name": "test", "id": 1, "category": category}
|
||||
)
|
||||
item = Item(**response.json())
|
||||
assert item.pk is not None
|
||||
|
||||
response = client.get("/items/")
|
||||
items = [Item(**item) for item in response.json()]
|
||||
assert items[0] == item
|
||||
|
||||
item.name = "New name"
|
||||
response = client.put(f"/items/{item.pk}", json=item.dict())
|
||||
assert response.json() == item.dict()
|
||||
|
||||
response = client.get("/items/")
|
||||
items = [Item(**item) for item in response.json()]
|
||||
assert items[0].name == "New name"
|
||||
|
||||
response = client.delete(f"/items/{item.pk}", json=item.dict())
|
||||
assert response.json().get("deleted_rows", "__UNDEFINED__") != "__UNDEFINED__"
|
||||
response = client.get("/items/")
|
||||
items = response.json()
|
||||
assert len(items) == 0
|
||||
```
|
||||
|
||||
!!!tip
|
||||
If you want to see more test cases and how to test ormar/fastapi see [tests][tests] directory in the github repo
|
||||
|
||||
!!!info
|
||||
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
|
||||
[tests]: https://github.com/collerek/ormar/tree/master/tests
|
||||
42
docs/fastapi/requests.md
Normal file
42
docs/fastapi/requests.md
Normal file
@ -0,0 +1,42 @@
|
||||
# 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).
|
||||
|
||||
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.
|
||||
|
||||
In sample below only last_name is required
|
||||
|
||||
```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 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
|
||||
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']
|
||||
```
|
||||
But if you cannot set default you will need additional pydantic Model.
|
||||
230
docs/fastapi/response.md
Normal file
230
docs/fastapi/response.md
Normal file
@ -0,0 +1,230 @@
|
||||
# Response
|
||||
|
||||
You can use ormar Models in `fastapi` response_model instead of pydantic models.
|
||||
|
||||
You can of course also mix `ormar.Model`s with `pydantic` ones if you need to.
|
||||
|
||||
One of the most common tasks in responses is excluding certain fields that you do not want to include in response data.
|
||||
|
||||
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 response
|
||||
|
||||
### 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
|
||||
class User(ormar.Model):
|
||||
class Meta:
|
||||
tablename: str = "users"
|
||||
metadata = metadata
|
||||
database = database
|
||||
|
||||
id: int = ormar.Integer(primary_key=True)
|
||||
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)
|
||||
category: str = ormar.String(max_length=255, default="User")
|
||||
```
|
||||
|
||||
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:
|
||||
|
||||
```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), save in the database and return the saved record without this field (which will also pass validation).
|
||||
|
||||
!!!Note
|
||||
Note that although you do not pass the **field value**, the **field itself** is still present in the `response_model` that means it **will be present in response data** and set to `None`.
|
||||
|
||||
If you want to fully exclude the field from the result read on.
|
||||
|
||||
### FastApi `response_model_exclude`
|
||||
|
||||
Fastapi has `response_model_exclude` that accepts a set (or a list) of field names.
|
||||
|
||||
That has it's limitation as `ormar` and `pydantic` accepts also dictionaries in which you can set exclude/include columns also on nested models (more on this below)
|
||||
|
||||
!!!Warning
|
||||
Note that you cannot exclude required fields when using `response_model` as it will fail during validation.
|
||||
|
||||
```python
|
||||
@app.post("/users/", response_model=User, response_model_exclude={"password"})
|
||||
async def create_user(user: User):
|
||||
return await user.save()
|
||||
```
|
||||
|
||||
Above endpoint can be queried like this:
|
||||
|
||||
```python
|
||||
from starlette.testclient import TestClient
|
||||
|
||||
client = TestClient(app)
|
||||
|
||||
with client as client:
|
||||
# note there is no pk
|
||||
user = {
|
||||
"email": "test@domain.com",
|
||||
"password": "^*^%A*DA*IAAA",
|
||||
"first_name": "John",
|
||||
"last_name": "Doe",
|
||||
}
|
||||
response = client.post("/users/", json=user)
|
||||
# note that the excluded field is fully gone from response
|
||||
assert "password" not in response.json()
|
||||
# read the response and initialize model out of it
|
||||
created_user = User(**response.json())
|
||||
# note pk is populated by autoincrement
|
||||
assert created_user.pk is not None
|
||||
# note that password is missing in initialized model too
|
||||
assert created_user.password is None
|
||||
```
|
||||
|
||||
!!!Note
|
||||
Note how in above example `password` field is fully gone from the response data.
|
||||
|
||||
Note that you can use this method only for non-required fields.
|
||||
|
||||
#### Nested models excludes
|
||||
|
||||
Despite the fact that `fastapi` allows passing only set of field names, so simple excludes, when using `response_model_exclude`, ormar is smarter.
|
||||
|
||||
In `ormar` you can exclude nested models using two types of notations.
|
||||
|
||||
One is a dictionary with nested fields that represents the model tree structure, and the second one is double underscore separated path of field names.
|
||||
|
||||
Assume for a second that our user's category is a separate model:
|
||||
|
||||
```python
|
||||
class BaseMeta(ormar.ModelMeta):
|
||||
metadata = metadata
|
||||
database = database
|
||||
|
||||
class Category(ormar.Model):
|
||||
class Meta(BaseMeta):
|
||||
tablename: str = "categories"
|
||||
|
||||
id: int = ormar.Integer(primary_key=True)
|
||||
name: str = ormar.String(max_length=255)
|
||||
priority: int = ormar.Integer(nullable=True)
|
||||
|
||||
|
||||
class User(ormar.Model):
|
||||
class Meta(BaseMeta):
|
||||
tablename: str = "users"
|
||||
|
||||
id: int = ormar.Integer(primary_key=True)
|
||||
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)
|
||||
category: Optional[Category] = ormar.ForeignKey(Category, related_name="categories")
|
||||
```
|
||||
|
||||
If you want to exclude `priority` from category in your response, you can still use fastapi parameter.
|
||||
```python
|
||||
@app.post("/users/", response_model=User, response_model_exclude={"category__priority"})
|
||||
async def create_user(user: User):
|
||||
return await user.save()
|
||||
```
|
||||
|
||||
Note that you can go in deeper models with double underscore, and if you wan't to exclude multiple fields from nested model you need to prefix them with full path.
|
||||
In example `response_model_exclude={"category__priority", "category__other_field", category__nested_model__nested_model_field}` etc.
|
||||
|
||||
!!!Note
|
||||
To read more about possible excludes and how to structure your exclude dictionary or set visit [fields](../queries/select-columns.md#fields) section of documentation
|
||||
|
||||
!!!Note
|
||||
Note that apart from `response_model_exclude` parameter `fastapi` supports also other parameters inherited from `pydantic`.
|
||||
All of them works also with ormar, but can have some nuances so best to read [dict](../models/methods.md#dict) part of the documentation.
|
||||
|
||||
### Exclude in `Model.dict()`
|
||||
|
||||
Alternatively you can just return a dict from `ormar.Model` and use .
|
||||
|
||||
Like this you can also set exclude/include as dict and exclude fields on nested models too.
|
||||
|
||||
!!!Warning
|
||||
Not using a `response_model` will cause api documentation having no response example and schema since in theory response can have any format.
|
||||
|
||||
```python
|
||||
@app.post("/users2/", response_model=User)
|
||||
async def create_user2(user: User):
|
||||
user = await user.save()
|
||||
return user.dict(exclude={'password'})
|
||||
# could be also something like return user.dict(exclude={'category': {'priority'}}) to exclude category priority
|
||||
```
|
||||
|
||||
!!!Note
|
||||
Note that above example will nullify the password field even if you pass it in request, but the **field will be still there** as it's part of the response schema, the value will be set to `None`.
|
||||
|
||||
If you want to fully exclude the field with this approach simply don't use `response_model` and exclude in Model's dict()
|
||||
|
||||
Alternatively you can just return a dict from ormar model.
|
||||
Like this you can also set exclude/include as dict and exclude fields on nested models.
|
||||
|
||||
!!!Note
|
||||
In theory you loose validation of response here but since you operate on `ormar.Models` the response data have already been validated after db query (as ormar model is pydantic model).
|
||||
|
||||
So if you skip `response_model` altogether you can do something like this:
|
||||
|
||||
```python
|
||||
@app.post("/users4/") # note no response_model
|
||||
async def create_user4(user: User):
|
||||
user = await user.save()
|
||||
return user.dict(exclude={'last_name'})
|
||||
```
|
||||
|
||||
!!!Note
|
||||
Note that when you skip the response_model you can now **exclude also required fields** as the response is no longer validated after being returned.
|
||||
|
||||
The cost of this solution is that you loose also api documentation as response schema in unknown from fastapi perspective.
|
||||
|
||||
### 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
|
||||
ResponseUser = User.get_pydantic(exclude={"password": ..., "category": {"priority"}})
|
||||
@app.post("/users3/", response_model=ResponseUser) # use the generated model here
|
||||
async def create_user3(user: User):
|
||||
return await user.save()
|
||||
```
|
||||
|
||||
!!!Note
|
||||
To see more examples and read more visit [get_pydantic](../models/methods.md#get_pydantic) part of the documentation.
|
||||
|
||||
|
||||
### Separate `pydantic` model
|
||||
```python
|
||||
class UserBase(pydantic.BaseModel):
|
||||
class Config:
|
||||
orm_mode = True
|
||||
|
||||
email: str
|
||||
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
|
||||
return await user.save()
|
||||
```
|
||||
Reference in New Issue
Block a user