Flask-Pydantic

Flask extension for integration of the awesome pydantic package with Flask.

Installation

python3 -m pip install Flask-Pydantic

Basics

URL query and body parameters

validate decorator validates query and body request parameters and makes them accessible two ways:

Using validate arguments, via flask's request variable

parameter type	`request` attribute name
query	`query_params`
body	`body_params`

Using the decorated function argument parameters type hints

URL path parameter

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.

Additional `validate` arguments

Success response status code can be modified via on_success_status parameter of validate decorator.
response_many parameter set to True enables serialization of multiple models (route function should therefore return iterable of models).
request_body_many parameter set to False analogically enables serialization of multiple models inside of the root level of request body. If the request body doesn't contain an array of objects 400 response is returned,
get_json_params - parameters to be passed to flask.Request.get_json function
If validation fails, 400 response is returned with failure explanation.

For more details see in-code docstring or example app.

Usage

Example 1: Query parameters only

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"
    )

See the full example app here

age query parameter is a required int

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"}

Example 2: URL path parameter

@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

Example 3: Request body only

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
    )

See the full example app here

Example 4: BOTH query paramaters and request body

# 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
  )

See the full example app here

Modify response status code

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.

Using the decorated function `kwargs`

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.

Model aliases

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(...)

Example app

For more complete examples see example application.

Configuration

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)

Contributing

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

TODOs:

header request parameters
cookie request parameters

subhamagr/flask-pydantic

Flask-Pydantic

Installation

Basics

URL query and body parameters

URL path parameter

Additional validate arguments

Usage

Example 1: Query parameters only

Example 2: URL path parameter

Example 3: Request body only

Example 4: BOTH query paramaters and request body

Modify response status code

Using the decorated function kwargs

Model aliases

Example app

Configuration

Contributing

TODOs:

Additional `validate` arguments

Using the decorated function `kwargs`