Skip to content

Xitzin

Application Framework for the Geminispace

Xitzin is a Gemini Application Framework that brings a modern Python developer experience to the Gemini protocol. Build Gemini capsules with familiar patterns: decorators for routing and type-annotated path parameters.

Quick Example

from xitzin import Xitzin, Request

app = Xitzin()

@app.gemini("/")
def home(request: Request):
    return "# Welcome to my capsule!"

@app.gemini("/user/{username}")
def profile(request: Request, username: str):
    return f"# {username}'s Profile"

@app.input("/search", prompt="Enter search query:")
def search(request: Request, query: str):
    return f"# Results for: {query}"

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

Key Features

  • FastAPI-inspired API

    Familiar decorator-based routing with @app.gemini() and automatic parameter extraction.

  • Certificate Authentication

    Built-in decorators for certificate-based authentication with @require_certificate.

  • Jinja2 Templates

    Gemtext-aware template engine with filters for links, headings, lists, and more.

  • Middleware Support

    Class-based and function-based middleware for logging, rate limiting, and custom processing.

  • Testing Utilities

    In-memory TestClient for testing your application without running a server.

  • Async Support

    Both sync and async handlers supported out of the box.

HTTP vs Gemini: A Quick Comparison

If you're coming from web development, here's how Gemini differs:

HTTP Concept Gemini Equivalent
GET /path gemini://host/path
Query strings ?q=foo Input prompts (status 10/11)
Cookies/Sessions Client certificates
HTML Gemtext (.gmi)
OAuth/JWT Certificate fingerprints
@app.get() @app.gemini()

Installation

pip install xitzin

Or with uv:

uv add xitzin

Next Steps