Build with AgilePy

Introduction

AgilePy is a Python micro-framework focused on server-rendered frontend views. It is built on top of Flask and uses Jinja2 for templating. The goal is to give you Flask's flexibility with a tighter, more opinionated project layout.

Installation

AgilePy requires Python 3.10 or newer. Install via pip:

pip install agilepy

Or clone the reference project from GitHub:

git clone https://github.com/josuamarcelc/AgilePy
cd AgilePy
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Hello, World

Create app.py:

from agilepy import AgilePy

app = AgilePy(__name__)

@app.route("/")
def home():
    return app.render("home.html", title="AgilePy")

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

Run it:

python app.py

Open http://localhost:5000 and you should see your first AgilePy page.

Routing

Routes are registered with the @app.route() decorator, identical to Flask. Support for path parameters and HTTP methods is included out of the box:

@app.route("/user/<int:user_id>")
def show_user(user_id):
    return app.render("user.html", user_id=user_id)

@app.route("/submit", methods=["POST"])
def submit():
    return {"ok": True}

Templates

Place templates in the templates/ directory. Render with app.render():

@app.route("/about")
def about():
    return app.render("about.html", year=2026)

Inside templates/about.html you have full Jinja2 syntax: inheritance, macros, filters, and includes.

Modules

AgilePy encourages organising routes into modules instead of class-based controllers. A module is just a Python file exposing functions registered through a tiny register_routes helper:

# views/home.py
def index():
    return app.render("home.html")

# routes.py
from views import home

def register_routes(app):
    app.add_url_rule("/", "home", home.index)

Static files

Drop your CSS, JS and images into the static/ directory. They are served from /static/<file> automatically.

Deploy with Gunicorn

For production, run AgilePy under Gunicorn:

gunicorn --workers 2 --threads 4 --bind 127.0.0.1:5000 app:application

Nginx reverse proxy

A minimal Nginx block proxying to the Gunicorn upstream:

location / {
    proxy_pass http://127.0.0.1:5000;
    proxy_set_header Host              $host;
    proxy_set_header X-Real-IP         $remote_addr;
    proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

Systemd service

Keep AgilePy running across reboots with a systemd unit:

[Unit]
Description=AgilePy
After=network.target

[Service]
User=www-data
WorkingDirectory=/var/www/myapp
ExecStart=/var/www/myapp/venv/bin/gunicorn \
  --workers 2 --threads 4 --bind 127.0.0.1:5000 app:application
Restart=always
RestartSec=2

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable --now agilepy

CLI commands

Common scripts you'll run during development:

• python app.py — start the dev server with autoreload
• gunicorn app:application — start a production server
• pip install -r requirements.txt — install dependencies
• python -m pytest — run the test suite

FAQ

Is AgilePy a replacement for Flask?

No. AgilePy is a thin layer over Flask that adds opinionated layout and conventions for frontend-rendered apps.

Can I use it for APIs?

Yes, but FastAPI is a better fit if your project is API-only. AgilePy shines for server-rendered HTML.

How do I report a bug?

Open an issue on GitHub with steps to reproduce.