flask-nova 0.1.1

Extra check using pydandic in flask application

FlaskNova

A modern and lightweight extension for Flask that brings FastAPI-style features like automatic OpenAPI schema, Swagger UI, request validation, typed routing, and structured responses.

---

🚀 Features

• ✅ Automatic OpenAPI 3.0 schema generation
• ✅ Built-in Swagger UI at /docs (configurable)
• ✅ Request validation using Pydantic models
• ✅ Response model serialization (Pydantic, dataclass, or custom class with to_dict)
• ✅ Docstring-based or keyword-based summary and description for endpoints
• ✅ Typed URL parameters (<int:id>, <uuid:id>, etc.)
• ✅ Customizable Swagger UI route path and OpenAPI metadata
• ✅ Configurable via FLASKNOVA_SWAGGER_ENABLED and FLASKNOVA_SWAGGER_ROUTE
• ✅ Clean modular routing with NovaBlueprint
• ✅ Built-in HTTP status codes (flasknova.status)
• ✅ Optional JWT auth and dependency injection helpers
• ✅ New: Form() parsing for form data
• ✅ New: @guard() decorator for combining multiple decorators (e.g. JWT + roles)
• ✅ Minimal boilerplate and highly extensible

---

📑 Table of Contents

• Why FlaskNova?
• Installation
• Quick Example
• Route Documentation
• Typed URL Parameters
• Swagger UI
• Response Models
• Form Parsing
• Guard Decorator
• Status Codes
• Error Handling
• Response Serialization
• Logging
• FAQ
• Learn More
• License
• Contributing

---

Why FlaskNova?

FlaskNova brings modern API development to Flask with a FastAPI-inspired design:

• Automatic OpenAPI/Swagger UI: Instantly document and test your API.
• Flexible serialization: Use Pydantic, dataclasses, or custom classes (with type hints).
• Dependency injection: Cleaner, more testable route logic.
• Unified error handling and status codes: Consistent and robust.
• Production-ready logging: Built-in, unified logger.
• Minimal boilerplate: Focus on your business logic, not plumbing.

---

Installation

pip install flask-nova

---

Quick Example

from flasknova import FlaskNova, NovaBlueprint, status
from pydantic import BaseModel

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

class User(BaseModel):
    username: str
    email: str

@api.route("/users", methods=["POST"], response_model=User, summary="Create a new user")
def create_user(data: User):
    return data, status.CREATED

app.register_blueprint(api)

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

Go to http://localhost:5000/docs to try it out in Swagger UI.

---

📝 Route Documentation Options

Using summary and description:

@api.route("/hello", summary="Say hello", description="Returns a greeting message.")
def hello():
    return {"msg": "Hello!"}

Or using a docstring:

@api.route("/hello")
def hello():
    """Say hello.

    Returns a greeting message to the user.
    """
    return {"msg": "Hello!"}

---

🔀 Typed URL Parameters

@api.route("/users/<int:user_id>", methods=["GET"])
def get_user(user_id: int):
    ...

Supported: int, float, uuid, path, string (default).

---

🧪 Enabling Swagger UI

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

Environment vars:

Variable	Default	Description
FLASKNOVA_SWAGGER_ENABLED	True	Disable Swagger UI if False
FLASKNOVA_SWAGGER_ROUTE	/docs	Change UI path

---

🔁 Response Models

• ✅ Pydantic models
• ✅ Dataclasses
• ✅ Custom classes (to_dict, dict, or dump)

import dataclasses

@dataclasses.dataclass
class User:
    id: int
    name: str

@api.route("/me", response_model=User)
def get_profile():
    return {"id": 1, "name": "nova"}

---

📦 Form Parsing

Use Form() to handle form data (like FastAPI’s Form).

from flasknova import FlaskNova, NovaBlueprint, Form, status
from pydantic import BaseModel

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

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

@api.route("/login", methods=["POST"])
def login(data: LoginForm = Form(LoginForm)):
    return {"msg": f"Welcome {data.username}"}, status.OK

app.register_blueprint(api)

---

🔐 Guard Decorator

Use @guard() to combine multiple decorators (e.g. JWT + roles).

from flasknova import FlaskNova, NovaBlueprint, guard, status
from flask_jwt_extended import jwt_required

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

@api.route("/secure", methods=["GET"])
@guard(jwt_required())
def secure_endpoint():
    return {"msg": "You are authenticated"}, status.OK

# Multiple decorators in one
@api.route("/admin", methods=["GET"])
@guard(jwt_required(), lambda fn: print("Extra check") or fn)
def admin_only():
    return {"msg": "Admin access granted"}, status.OK

---

Status Codes

from flasknova import status

print(status.OK)   # 200
print(status.CREATED)  # 201
print(status.UNPROCESSABLE_ENTITY)  # 422

---

Error Handling

from flasknova import HTTPException, status

raise HTTPException(
    status_code=status.NOT_FOUND,
    detail="User not found",
    title="Not Found"
)

---

Response Serialization & Custom Responses

from flask import make_response, jsonify

@api.route("/custom", methods=["GET"])
def custom():
    data = {"message": "Custom response"}
    response = make_response(jsonify(data), 201)
    response.headers['X-Custom-Header'] = 'Value'
    return response

---

Logging

from flasknova import logger
logger.info("FlaskNova app started!")

---

FAQ

Why don't my custom class fields appear in Swagger UI?

You must add class-level type hints.

Why does my dataclass or custom class not validate requests?

Only Pydantic models are used for request validation.

Can I use Marshmallow schemas for request validation?

No, Marshmallow is only supported for response serialization.

---

📖 Learn More

• Flask Documentation
• Pydantic Docs

---

📚 License

MIT License

---

🤝 Contributing

• Fork the repo, create your branch from main
• Write tests and keep code clean
• Open a PR with explanation

Issues and features: GitHub Issues

---

📦 PyPI Release

🔗 FlaskNova on PyPI 🔗 GitHub Release Notes