Flask-Jeroboam

English | Français

Documentation: https://flask-jeroboam.readthedocs.io/

Source Code: https://github.com/jcbianic/flask-jeroboam

What is Flask-Jeroboam?

Flask-Jeroboam brings FastAPI's approach to Flask. If you like how FastAPI handles request parsing, response validation, and automatic docs—but you need Flask instead—this is for you.

It inspects your endpoint function signatures and handles validation, serialization, and OpenAPI docs automatically. It's just a thin layer connecting Flask to Pydantic the way FastAPI does.

Why Flask-Jeroboam?

You have existing Flask code — Refactoring to FastAPI isn't an option. Jeroboam is a drop-in extension.

You rely on Flask's ecosystem — Flask-SQLAlchemy, Flask-Login, Flask-Admin, and dozens of other extensions just work. FastAPI doesn't integrate with them.

You serve both HTML and APIs — Some apps need to render templates alongside JSON endpoints. Flask handles both naturally.

You prefer WSGI — Whether for infrastructure reasons or team preference, WSGI is your deployment model.

You want FastAPI's development experience — Type-safe endpoints with automatic documentation, without switching frameworks.

Key Features

• Per-Parameter Validation — Type hints on endpoint arguments automatically validate and parse request data
• Response Validation — Define response models; Jeroboam validates outgoing data matches the schema
• Automatic OpenAPI Docs — Interactive API documentation generated automatically
• Type Safety — Use Python type hints to make code clearer and catch bugs earlier
• Drop-In Compatible — Works with existing Flask applications and extensions

Quick Install

$ pip install flask-jeroboam

Full setup guide with dependency management: Installation

A Taste

from flask_jeroboam import Jeroboam, InboundModel, OutboundModel
from typing import Optional

app = Jeroboam(__name__)

class WineQuery(InboundModel):
    page: int = 1
    search: Optional[str] = None

class WineOut(OutboundModel):
    name: str
    appellation: str

@app.get("/wines", response_model=list[WineOut])
def list_wines(query: WineQuery):
    return get_wines(query.page, query.search)

Query params are parsed and validated from the type hints. The response is filtered and serialized against WineOut. Hit /docs for the interactive OpenAPI interface.

Next Steps

New to Jeroboam? Start with the Getting Started guide.

Ready to build? Follow the Tutorial for a complete example.

Need specifics? Check the How-to Guides for common tasks.

Want deeper understanding? Read the Concepts section.

How Does It Compare?

Flask-Jeroboam sits at a specific point in the landscape—closer to FastAPI than to flask-openapi3 or flask-restx, but firmly in the Flask ecosystem.

See the full Comparison Guide for in-depth analysis.

About the Name

A Jeroboam is a large wine bottle (5 litres in Bordeaux, 3 litres elsewhere) designed for fine wines that age well. The larger surface-area-to-volume ratio slows oxidation. Temperature stays more stable. They're built to last without degrading your wine.

The project aims for the same durability: an API that stays solid and reliable as it ages.

License

Distributed under the MIT License. Flask-Jeroboam is free and open source.

Issues

Found a bug or want to suggest a feature? Please file an issue using the available templates.

Credits

Inspired by @tiangolo's FastAPI.

Built on Flask and Pydantic—both excellent projects.