Getting Started

Flasgo requires Python 3.14 or newer. These guides describe the 0.11.0 API. Start a project with uv:

uv init --python 3.14
uv add flasgo

This installs the published package. For an existing project, see version checks and upgrades.

Create app.py:

import os
import secrets

from flasgo import Flasgo, Request, Response

app = Flasgo(
    settings={
        "DEBUG": True,
        "SECRET_KEY": os.environ.get(
            "FLASGO_SECRET_KEY",
            secrets.token_urlsafe(32),
        ),
        "ALLOWED_HOSTS": {"127.0.0.1", "localhost"},
        # Local HTTP only. Keep both settings True in production.
        "SESSION_COOKIE_SECURE": False,
        "CSRF_COOKIE_SECURE": False,
    }
)


@app.get("/")
async def home() -> dict[str, str]:
    return {"framework": "flasgo", "status": "ok"}


@app.post("/echo")
async def echo(request: Request) -> Response:
    payload = await request.json()
    return Response.json({"received": payload}, status_code=201)

Run the development server:

uv run flasgo run app.py --reload

Flasgo also accepts an import string:

uv run flasgo run package.module:app --reload

The CLI uses Uvicorn’s H11 and websockets-sansio implementations with lifespan enabled, no server header, proxy-header trust disabled, bounded HTTP request heads, bounded WebSocket messages and queues, and a default concurrency limit. Flasgo also applies body, head, and read-time limits at the application boundary. Configure the production server and trusted proxy explicitly rather than copying development settings.

Handler return values

Handlers may be synchronous or asynchronous. Flasgo converts these values into responses:

@app.get("/text")
def text():
    return "plain text"


@app.get("/json")
def json_response():
    return {"ok": True}


@app.get("/created")
def created():
    return {"created": True}, 201, {"x-result": "created"}


@app.delete("/empty")
def empty():
    return None  # 204 No Content

You can also return bytes, a list, or a Response directly.

Version checks and upgrades

Flasgo 0.11.0 is available from PyPI and GitHub releases, matching the framework checkout and these guides. See the 0.11.0 changes for upgrade considerations.

Check the version installed in your project:

uv run python -c 'from importlib.metadata import version; print(version("flasgo"))'

To update an existing registry installation to the newest published version allowed by its constraints:

uv lock --upgrade-package flasgo
uv sync

If your project pins an older version or excludes 0.11.0, update its dependency constraint first. Check the installed version after updating and run your application’s tests.

For 0.11.0, upgrade SQLAlchemy to 2.0 or newer before using flasgo db, replace any imports of underscore-prefixed helpers from flasgo.request or flasgo.session with the private flasgo._request and flasgo._session modules, check that JWT secrets are random bytes rather than PEM, SSH, DER, or JWK text, and remove any ASGI root_path prefix from DOCS_PATH, OPENAPI_PATH, METRICS_PATH, and OTEL_EXCLUDED_PATHS. If you are upgrading from 0.9.1 or older, also review the 0.10.0 changes: ALLOWED_HOSTS and CSRF_TRUSTED_ORIGINS entries, parameter marker placement, route methods values, after_request hooks that now also see 404, 405, and authentication denials, empty 204 and 304 bodies, SSE heartbeat intervals, and async template rendering. If you are upgrading from 0.9.0 or older, also review the 0.9.1 changes: route conflicts, boolean configuration values, session changes after exceptions, and streaming cleanup deadlines. The 0.9.0 additions remain available: response contracts and shared storage are opt-in, and switching to server-side sessions requires existing users to log in again.

Using the development code

To work on the framework itself or test changes from a local checkout, install it in editable mode. If your project is next to the framework checkout:

uv add --editable ../flasgo

For Redis or Valkey support from the same checkout:

uv add --editable ../flasgo --extra redis

These paths refer to the framework repository, not this Astro documentation repository. Use Python 3.14 or newer. For a deployable build, use a reviewed, immutable source revision and its verified dependencies instead of a mutable editable checkout.

Before production

• Set DEBUG=False.
• Load a stable SECRET_KEY of at least 32 characters from a secret store.
• Set ALLOWED_HOSTS to the service’s real hostnames.
• Keep secure session and CSRF cookies enabled.
• Terminate TLS at a trusted reverse proxy or load balancer.
• Run uv run flasgo check app.py before deployment.

Continue with HTTP applications, Request Data and Dependencies, or WebSockets and application lifecycle.