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):
pass
flask_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_status
parameter ofvalidate
decorator. response_many
parameter set toTrue
enables serialization of multiple models (route function should therefore return iterable of models).request_body_many
parameter set toFalse
analogically enables serialization of multiple models inside of the root level of request body. If the request body doesn't contain an array of objects400
response is returned,get_json_params
- parameters to be passed toflask.Request.get_json
function- If validation fails,
400
response 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]
# 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"
)
age
query parameter is a requiredint
curl --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"}, 400
class RequestBodyModel(BaseModel):
name: str
nickname: Optional[str]
# 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]
# 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
validate
decorator
@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):
...
class Config:
alias_generator = modify_key
allow_population_by_field_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