Skip to main content

No project description provided

Project description


Build Status GitHub PyPI - Python Version

Provide OpenAPI document and validation for flask service.

Mainly built for Machine Learning Model services.

If you're using Falcon, check my another library Falibrary.


  • Generate API document with Redoc UI or Swagger UI :yum:
  • Less boilerplate code, annotations are really easy-to-use :sparkles:
  • Validate query, JSON data, response data with pydantic :wink:
  • Better HTTP exceptions for API services (default & customized) (JSON instead of HTML) :grimacing:

Quick Start

install with pip install flaskerk (Python 3.6+)

Simple demo

from flask import Flask, request, jsonify
from flaskerk import Flaskerk
from pydantic import BaseModel

class Query(BaseModel):
    text: str

app = Flask(__name__)
api = Flaskerk()

def classify():
    return jsonify(label=0)

if __name__ == "__main__":

Changes you need to make:

  • create model with pydantic
  • decorate the route function with Flaskerk.validate()
  • specify which part you need in validate
    • query (args in url)
    • data (JSON data from request)
    • resp (response) this will be transformed to JSON data after validation
    • x (HTTP Exceptions list)
    • tags (tags for this API route)
  • register to Flask application

After that, this library will help you validate the incoming request and provide API document in /docs.

Parameters in Flaskerk.validate Corresponding parameters in Flask
query request.query
data request.json_data
resp \
x \

For more details, check the document.

More feature

from flask import Flask, request
from pydantic import BaseModel, Schema
from random import random
from flaskerk import Flaskerk, HTTPException

app = Flask(__name__)
api = Flaskerk(
    title='Demo Service',

class Query(BaseModel):
    text: str

class Response(BaseModel):
    label: int
    score: float = Schema(

class Data(BaseModel):
    uid: str
    limit: int
    vip: bool

e233 = HTTPException(code=233, msg='lucky for you')

@app.route('/api/predict/<string(length=2):source>/<string(length=2):target>', methods=['POST'])
@api.validate(query=Query, data=Data, resp=Response, x=[e233], tags=['model'])
def predict(source, target):
    predict demo

    demo for `query`, `data`, `resp`, `x`
    print(f'=> from {source} to {target}')  # path
    print(f'Data: {request.json_data}')  # Data
    print(f'Query: {request.query}')  # Query
    if random() < 0.5:
        e233.abort('bad luck')
    return Response(label=int(10 * random()), score=random())

if __name__ == '__main__':

try it with http POST ':5000/api/predict/zh/en?text=hello' uid=0b01001001 limit=5 vip=true

Open the docs in .

For more examples, check examples.


Can I just do the validation without generating API document?

Sure. If you don't register it to Flask application, there won't be document routes.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for flaskerk, version 0.6.3
Filename, size File type Python version Upload date Hashes
Filename, size flaskerk-0.6.3-py3-none-any.whl (11.7 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size flaskerk-0.6.3.tar.gz (11.0 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page