Flask extension for integration of the awesome pydantic package with Flask.
python3 -m pip install Flask-Pydantic
validate decorator validates query, body and form-data request parameters and makes them accessible two ways:
| parameter type | request attribute name |
|---|---|
| query | query_params |
| body | body_params |
| form | form_params |
If you use annotated path URL path parameters as follows
@app.route("/users/<user_id>", methods=["GET"])
@validate()
def get_user(user_id: str):
passflask_pydantic will parse and validate user_id variable in the same manner as for body and query parameters.
- Success response status code can be modified via
on_success_statusparameter ofvalidatedecorator. response_manyparameter set toTrueenables serialization of multiple models (route function should therefore return iterable of models).request_body_manyparameter set toFalseanalogically enables serialization of multiple models inside of the root level of request body. If the request body doesn't contain an array of objects400response is returned,get_json_params- parameters to be passed toflask.Request.get_jsonfunction- If validation fails,
400response is returned with failure explanation.
For more details see in-code docstring or example app.
Simply use validate decorator on route function.
❗ Be aware that @app.route decorator must precede @validate (i. e. @validate must be closer to the function declaration).
from typing import Optional
from flask import Flask, request
from pydantic import BaseModel
from flask_pydantic import validate
app = Flask("flask_pydantic_app")
class QueryModel(BaseModel):
age: int
class ResponseModel(BaseModel):
id: int
age: int
name: str
nickname: Optional[str] = None
# Example 1: query parameters only
@app.route("/", methods=["GET"])
@validate()
def get(query: QueryModel):
age = query.age
return ResponseModel(
age=age,
id=0, name="abc", nickname="123"
)agequery parameter is a requiredintcurl --location --request GET 'http://127.0.0.1:5000/'- if none is provided the response contains:
{ "validation_error": { "query_params": [ { "loc": ["age"], "msg": "field required", "type": "value_error.missing" } ] } } - for incompatible type (e. g. string
/?age=not_a_number) curl --location --request GET 'http://127.0.0.1:5000/?age=abc'{ "validation_error": { "query_params": [ { "loc": ["age"], "msg": "value is not a valid integer", "type": "type_error.integer" } ] } }
- likewise for body parameters
- example call with valid parameters:
curl --location --request GET 'http://127.0.0.1:5000/?age=20'
-> {"id": 0, "age": 20, "name": "abc", "nickname": "123"}
@app.route("/character/<character_id>/", methods=["GET"])
@validate()
def get_character(character_id: int):
characters = [
ResponseModel(id=1, age=95, name="Geralt", nickname="White Wolf"),
ResponseModel(id=2, age=45, name="Triss Merigold", nickname="sorceress"),
ResponseModel(id=3, age=42, name="Julian Alfred Pankratz", nickname="Jaskier"),
ResponseModel(id=4, age=101, name="Yennefer", nickname="Yenn"),
]
try:
return characters[character_id]
except IndexError:
return {"error": "Not found"}, 400class RequestBodyModel(BaseModel):
name: str
nickname: Optional[str] = None
# Example2: request body only
@app.route("/", methods=["POST"])
@validate()
def post(body: RequestBodyModel):
name = body.name
nickname = body.nickname
return ResponseModel(
name=name, nickname=nickname,id=0, age=1000
)# Example 3: both query paramters and request body
@app.route("/both", methods=["POST"])
@validate()
def get_and_post(body: RequestBodyModel,query: QueryModel):
name = body.name # From request body
nickname = body.nickname # From request body
age = query.age # from query parameters
return ResponseModel(
age=age, name=name, nickname=nickname,
id=0
)class RequestFormDataModel(BaseModel):
name: str
nickname: Optional[str] = None
# Example2: request body only
@app.route("/", methods=["POST"])
@validate()
def post(form: RequestFormDataModel):
name = form.name
nickname = form.nickname
return ResponseModel(
name=name, nickname=nickname,id=0, age=1000
)The default success status code is 200. It can be modified in two ways
- in return statement
# necessary imports, app and models definition
...
@app.route("/", methods=["POST"])
@validate(body=BodyModel, query=QueryModel)
def post():
return ResponseModel(
id=id_,
age=request.query_params.age,
name=request.body_params.name,
nickname=request.body_params.nickname,
), 201- in
validatedecorator
@app.route("/", methods=["POST"])
@validate(body=BodyModel, query=QueryModel, on_success_status=201)
def post():
...Status code in case of validation error can be modified using FLASK_PYDANTIC_VALIDATION_ERROR_STATUS_CODE flask configuration variable.
Instead of passing body and query to validate, it is possible to directly
defined them by using type hinting in the decorated function.
# necessary imports, app and models definition
...
@app.route("/", methods=["POST"])
@validate()
def post(body: BodyModel, query: QueryModel):
return ResponseModel(
id=id_,
age=query.age,
name=body.name,
nickname=body.nickname,
)This way, the parsed data will be directly available in body and query.
Furthermore, your IDE will be able to correctly type them.
Pydantic's alias feature is natively supported for query and body models. To use aliases in response modify response model
def modify_key(text: str) -> str:
# do whatever you want with model keys
return text
class MyModel(BaseModel):
...
model_config = ConfigDict(
alias_generator=modify_key,
populate_by_name=True
)and set response_by_alias=True in validate decorator
@app.route(...)
@validate(response_by_alias=True)
def my_route():
...
return MyModel(...)
For more complete examples see example application.
The behaviour can be configured using flask's application config
FLASK_PYDANTIC_VALIDATION_ERROR_STATUS_CODE - response status code after validation error (defaults to 400)
Additionally, you can set FLASK_PYDANTIC_VALIDATION_ERROR_RAISE to True to cause
flask_pydantic.ValidationError to be raised with either body_params,
form_params, path_params, or query_params set as a list of error
dictionaries. You can use flask.Flask.register_error_handler to catch that
exception and fully customize the output response for a validation error.
Feature requests and pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.
- clone repository
git clone https://github.com/bauerji/flask_pydantic.git cd flask_pydantic - create virtual environment and activate it
python3 -m venv venv source venv/bin/activate - install development requirements
python3 -m pip install -r requirements/test.pip
- checkout new branch and make your desired changes (don't forget to update tests)
git checkout -b <your_branch_name>
- run tests
python3 -m pytest
- if tests fails on Black tests, make sure You have your code compliant with style of Black formatter
- push your changes and create a pull request to master branch
- header request parameters
- cookie request parameters