DEV Community: Emmanuel Buah-Kwofie

Why Use Flask-Nova: Modern APIs on Top of Vanilla Flask

Emmanuel Buah-Kwofie — Fri, 25 Jul 2025 10:35:57 +0000

If you love Flask but wish it had type hints, automatic OpenAPI docs, dependency injection, and better DX — Flask-Nova is for you.

The Problem with Vanilla Flask
Let’s say you want to build a simple JSON API with Flask. You’d probably write something like:

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route("/greet", methods=["POST"])
def greet():
    data = request.get_json()
    name = data.get("name")
    return jsonify({"message": f"Hello, {name}!"})

It works. But now imagine:

You want to validate the request data.
You want OpenAPI docs for your frontend team.
You want typed parameters from the URL or query.
You want better error handling and testing.
You want some structure, without rewriting everything.

Soon, your simple app becomes a tangle of decorators, manual checks, and custom logic. And if you want more modern tooling like FastAPI offers, you're suddenly looking at rebuilding everything using ASGI and leaving behind the familiar Flask ecosystem.

Flask-Nova is a modern framework built on top of Flask. It brings typed routing, OpenAPI generation, dependency injection, and other developer-friendly features — all while keeping your app fully compatible with the Flask and WSGI world.

What it gives you:

Typed route parameters
Automatic Swagger / OpenAPI docs
Dependency injection via Depend()
Clean logging and built-in exception handling
Works with dataclass, pydantic, or plain classes
No ASGI, no Starlette — just Flask

Why Not Just Use FastAPI?

FastAPI is amazing. But Flask-Nova isn’t trying to replace it.
Instead, Flask-Nova is for developers who:

Still prefer Flask or are maintaining existing Flask apps
Want FastAPI-like features but without switching to ASGI
Need something lightweight, sync-friendly, and deployable anywhere (including platforms where ASGI isn’t easy to run) It’s like giving your old Flask app a supercharged dev experience without a full rewrite.

A Taste of Flask-Nova

from flask_nova import FlaskNova
from pydantic import BaseModel

app = FlaskNova(__name__)

class GreetRequest(BaseModel):
    name: str

@app.post("/greet")
def greet(data: GreetRequest):
    """Greet someone
    ---
    Returns a personalized greeting message.
    """
    return {"message": f"Hello, {data.name}!"}

Your request is validated.
Your route is typed.
Your docstring becomes OpenAPI docs (auto-generated).
Swagger UI is available at /docs.

All this, without leaving Flask.

Built-in Tools That Matter
Dependency Injection

from flask_nova import Depend

def get_user():
    return {"id": 1, "name": "Alice"}

@app.get("/me")
def me(user=Depend(get_user)):
    return {"user": user}

OpenAPI from Docstrings

"""Get current time
---
description: Returns the current UTC time.
responses:
  200:
    description: Current time in ISO format.
"""

When Should You Use Flask-Nova?

Use Flask-Nova if:

You like Flask and don’t want to switch to FastAPI
You want a modern dev experience in a WSGI-compatible setup
You’re building APIs, microservices, or internal tools with Python
You want clean, typed code and real documentation — without the hassle

Try It Now

GitHub: https://github.com/treasuremani/flask-nova
Pypi: https://pypi.org/project/flask-nova/
Quickstart Docs: Coming soon!

Flask-Nova isn’t trying to compete with FastAPI — it’s for developers who want to stay in the Flask world while still enjoying modern Python features.

If that sounds like you, give it a try. Drop a star, ask a question, or submit feedback. Let’s build clean, modern APIs — the Flask way.

Introducing Flask-Nova: Zero-Boilerplate APIs with Docs & Type Safety

Emmanuel Buah-Kwofie — Wed, 23 Jul 2025 08:23:22 +0000

Flask is celebrated for its simplicity and flexibility, but let's be honest, building a modern API with features like authentication, validation, and comprehensive documentation often becomes a repetitive chore.

That's why I created Flask-Nova—a modern extension for Flask designed to accelerate API development. It comes with automatic OpenAPI documentation and type-safe input models built right in, so you can focus on what matters: your application's logic.

🔗 PyPI: https://pypi.org/project/flask-nova/

💻 GitHub: https://github.com/manitreasure1/flasknova

📘 Example App: https://github.com/manitreasure1/flask-nova-tutorials

🔥 Key Features

✅ Auto-generated Swagger docs (/docs): Get interactive API documentation, enabled with a single line of code and easily customizable.
✅ Typed route inputs using Pydantic-style models: Ensure data integrity with clear, concise type hints.
✅ Decorator-based routing with zero boilerplate: Define your routes cleanly and efficiently.
✅ Built-in HTTPException for clean error handling: Manage API errors gracefully.
✅ status helpers (e.g., status.CREATED): Use semantic HTTP status codes easily.
✅ Depend() for clean dependency injection: Organize your code with reusable components.
✅ Extensible and Pythonic design: Enjoy a familiar and flexible development experience.
✅ Compatible with native Flask: Seamlessly integrate with your existing Flask projects.

🚀 Installation
pip install flask-nova

Code Examples
Basic Route with Type-Safe Input
This example shows how to define a route that automatically validates incoming request data based on a Pydantic-style model.

from flask_nova import FlakNova, NovaBlueprint
app = FlaskNova(__name__)
route = NovaBlueprint("dev",__name__)
class RegisterData(RequestModel):
    username: str
    email: str
@route.post("/register")
def register(data: RegisterData):
    return {"msg": "User registered", "data": data.model_dump()}

# Register the blueprint (assuming 'app' is your FlaskNova instance)
app.register_blueprint(route)

# To run this minimal example:
# if __name__ == "__main__":
#     app.run(debug=True)

This endpoint automatically validates the incoming request, and its JSON schema is included in the auto-generated API documentation.

Dependecy Injection
Leverage Depend() to inject dependencies into your route functions, making your code modular and testable.

from flask_nova import Depend,FlaskNova NovaBlueprint

app = FlaskNova(__name__) # Use Flask for the base app
route = NovaBlueprint("dev", __name__)

def get_current_user():
    # In a real app, this would fetch the authenticated user
    return {"id": 1, "username": "admin"}

@route.get("/me")
def me(user=Depend(get_current_user)):
    return {"user": user}

# Register the blueprint
app.register_blueprint(route)

# if __name__ == "__main__":
#     app.run(debug=True)

Route Metadata: Summary, Description, and Response Model
Enhance your API documentation by adding a summary, description, response_model, and tags to your routes.

from flask_nova import FlaskNova NovaBlueprint
from pydantic import BaseModel

app = FlaskNova(__name__) 
auth_bp = NovaBlueprint("auth", __name__)

class LoginInput(BaseModel):
    username: str
    password: str

class LoginOut(BaseModel):
    access_token: str
    refresh_token: str

@auth_bp.route(
    "/login",
    methods=["POST"],
    summary="Login user",
    description="Authenticate user and return JWT access and refresh tokens.",
    response_model=LoginOut,
    tags=["Auth"]
)
def login(data: LoginInput):
    # In a real application, this would handle user authentication
    return {"access_token": "abc.123.xyz", "refresh_token": "def.456.uvw"}

# Register the blueprint
app.register_blueprint(auth_bp)

# if __name__ == "__main__":
#     app.run(debug=True)

Error Handling with HTTPException and status Helpers

from flask_nova import route, FlaskNova, NovaBlueprint, HTTPException, status

app = FlaskNova(__name__)
api = NovaBlueprint("api", __name__)

items = {
    1: {"id": 1, "name": "Item One"},
    2: {"id": 2, "name": "Item Two"}
}

@api.route("/items/<int:item_id>", methods=["GET"])
def get_item(item_id: int):
    item = items.get(item_id)
    if not item:
        raise HTTPException(
            status_code=status.NOT_FOUND,
            detail=f"Item {item_id} not found",
            title="Not Found"
        )
    return item

@api.route("/items", methods=["POST"])
def create_item():
    new_id = max(items.keys()) + 1
    item = {"id": new_id, "name": f"Item {new_id}"}
    items[new_id] = item
    return item, status.CREATED

app.register_blueprint(api)

# if __name__ == "__main__":
#     app.run(debug=True)

Common status Codes
Flask-Nova includes a status module for easy access to common HTTP status codes.

from flask_nova import status

print(status.OK)                  # 200
print(status.CREATED)             # 201
print(status.NO_CONTENT)          # 204
print(status.BAD_REQUEST)         # 400
print(status.UNAUTHORIZED)        # 401
print(status.FORBIDDEN)           # 403
print(status.NOT_FOUND)           # 404
print(status.CONFLICT)            # 409
print(status.UNPROCESSABLE_ENTITY)# 422
print(status.INTERNAL_SERVER_ERROR) # 500

Built-in logging
Flask-Nova integrates a simple, colorful logging system for better development feedback.

from flask_nova import get_flasknova_logger
log = get_flasknova_logger()
#or simply: from flask_nova import logger

✅ This endpoint is automatically validated
✅ JSON schema is included in the docs
✅ Swagger UI available at /docs

Why Flask-Nova?
As a Flask developer, I deeply appreciate its flexibility. However, I consistently found myself repeating the same setup tasks across every project:

Manually parsing request data.
Writing input validators from scratch.
Setting up Swagger UI.
Implementing JWT authentication logic.
Documenting routes by hand.

I built Flask-Nova to eliminate this friction. Now, I can:

Focus on writing real features
Get fully-documented APIs out of the box
Maintain a Pythonic and type-safe codebase.

Configuration Tips
Flask-Nova allows easy customization of your API environment:

Enable and Customize Swagger UI
To make your API documentation available at /docs (or a custom route), you need to call app.setup_swagger(). This method also allows you to customize the API's title, description, version, and other important metadata.

if __name__ == '__main__':
    app.setup_swagger(info={
        "title": "FlaskNova API test",
        "version": "1.2.3",
        "description": "Beautiful API for modern apps.",
        "termsOfService": "https://example.com/terms",
        "contact": {
            "name": "Team FlaskNova",
            "url": "https://github.com/flasknova",
            "email": "support@flasknova.dev"
        },
        "license": {
            "name": "MIT",
            "url": "https://opensource.org/licenses/MIT"
        }
    })
    # app.run(debug=True)

Change Swagger UI Route
By default, your API documentation is served at /docs. You can change this by setting the following environment variable:

FLASKNOVA_SWAGGER_ROUTE=/api-docs
Now your docs will be available at /api-docs instead.

Disable Docs in Production

To prevent exposing internal documentation in production, simply disable the Swagger UI with:
FLASKNOVA_SWAGGER_ENABLED=False

This will hide the auto-generated docs while keeping your API fully functional.

🧪 Example App
If you want to see Flask-Nova in action, check out this simple example app repository:
👉 Flask-Nova Example App on GitHub
https://github.com/manitreasure1/flask-nova-tutorials.git

🙏 Feedback & Contributions Welcome
Flask-Nova is an open-source passion project, and I'd love your help to make it even better!

If you:

Like the idea → Please ⭐ the GitHub repo
Found a bug → Open an issue
Have an idea → Let's discuss! Want to contribute → Pull Requests are always welcome!

GitHub: https://github.com/manitreasure1/flasknova

PyPI: https://pypi.org/project/flask-nova/