Quick Start Guide¶

This guide will help you create your first Gobstopper application in minutes.

Your First Application¶

Create a file called app.py:

from gobstopper import Gobstopper, Request, jsonify

app = Gobstopper(__name__)

@app.get("/")
async def hello(request: Request):
    return jsonify({"message": "Hello from Gobstopper!"})

@app.get("/users/<user_id>")
async def get_user(request: Request, user_id: str):
    return jsonify({"user_id": user_id, "name": f"User {user_id}"})

Running the Application¶

Run your application with the Gobstopper CLI:

gobstopper run --reload

Or with Granian directly:

granian --interface rsgi --reload app:app

Visit http://localhost:8000 in your browser to see your application running.

Type-Safe Request Validation¶

Gobstopper supports automatic request validation using msgspec:

from gobstopper import Gobstopper, Request, jsonify
from msgspec import Struct

app = Gobstopper(__name__)

class User(Struct):
    name: str
    email: str
    age: int = 0

@app.post("/api/users")
async def create_user(request: Request, user: User):
    # user is automatically validated!
    # Returns 422 if validation fails
    return jsonify({"created": user.name, "email": user.email})

Templates¶

Enable Jinja2 templates:

from gobstopper import Gobstopper, Request

app = Gobstopper(__name__)
app.init_templates("templates")

@app.get("/")
async def index(request: Request):
    return await app.render_template("index.html",
                                    message="Hello World!")

Create templates/index.html:

<!DOCTYPE html>
<html>
<head>
    <title>Gobstopper App</title>
</head>
<body>
    <h1>{{ message }}</h1>
</body>
</html>

Background Tasks¶

Add background task processing:

from gobstopper import Gobstopper, Request, jsonify, TaskPriority
import asyncio

app = Gobstopper(__name__)

@app.task("send_email", "notifications")
async def send_email(to: str, subject: str):
    await asyncio.sleep(1)  # Simulate work
    print(f"Email sent to {to}: {subject}")
    return {"status": "sent"}

@app.post("/api/notify")
async def notify(request: Request):
    data = await request.get_json()

    task_id = await app.add_background_task(
        "send_email",
        "notifications",
        TaskPriority.HIGH,
        to=data["email"],
        subject=data["subject"]
    )

    return jsonify({"task_id": task_id})

# Start workers
@app.on_startup
async def startup():
    await app.start_task_workers("notifications", worker_count=2)

WebSockets¶

Add WebSocket support:

from gobstopper import Gobstopper

app = Gobstopper(__name__)

@app.websocket("/ws/chat")
async def chat_handler(websocket):
    await websocket.accept()

    while True:
        message = await websocket.receive()
        await websocket.send_text(f"Echo: {message.data}")

Configuration Files¶

Create a production.toml config:

app = "app:app"
host = "0.0.0.0"
port = 8080
workers = 4
threads = 2
reload = false

Run with config:

gobstopper run --config production

Next Steps¶

tutorial/index - Complete tutorial series
api/application - Application API reference
features/background_tasks - Background tasks guide
features/websockets - WebSocket guide
Command Line Interface - CLI tools documentation