Dreaming Electric Sheep (des)

High-performance CPython 3.13+ web stack built directly on Granian RSGI with startup-compiled msgspec validation, native HTMX support, and interactive route inspection.

Installation

pip install "dreaming-electric-sheep[standard]"

[standard] includes granian (RSGI), typer, rich, msgspec, Jinja2, and uvloop (Linux/macOS).

Quickstart

1. Scaffold a project

Create a new REST API project (or use -t fullstack for HTMX + Jinja2 as default):

des new my_api -t api
cd my_api

Templates available:

• -t api: REST API with msgspec.Struct validation and Scalar docs.
• -t fullstack: Jinja2 templates, HTMX fragments, Tailwind CDN, and SSE streaming.
• -t minimal: Single-file lightweight microservice.

2. Start the development server

des dev

The server starts on http://127.0.0.1:8000 with auto-reload enabled. Interactive API documentation is available at http://127.0.0.1:8000/docs.

3. Inspect the compiled route pipeline

Verify how routes, parameter decoders, and handlers are resolved at startup:

des why POST /items

Output:

Route:      POST /items
Handler:    app:create_item
Binders:
  • data: FromJSON[CreateItemInput] (pre-compiled msgspec decoder)
OpenAPI:    Documented in /openapi.json (schema: CreateItemInput)

Example

Here is a standard app.py combining schema validation, HTMX fragment responses, and real-time SSE streaming:

from des import Application, get, post, fragment, sse_stream
from msgspec import Struct

app = Application()

class Item(Struct):
    id: int
    name: str
    price: float

# Pre-compiled msgspec validation with structured 422 errors
@post("/api/items")
def create_item(data: Item):
    return {"status": "created", "item": data}

# First-class HTMX fragment response
@get("/items/{item_id}/row")
def item_row(item_id: int):
    return fragment(f"<tr id='item-{item_id}'><td>Item #{item_id}</td></tr>")

# Native Server-Sent Events (SSE) streaming
@get("/events")
def stream_events():
    async def feed():
        for count in range(10):
            yield {"event": "tick", "count": count}
    return sse_stream(feed)

Features

• Granian RSGI Transport: Native C/Rust socket communication bypassing ASGI message loop overhead.
• Pre-Compiled Validation: msgspec.Struct decoders compiled at route registration time; produces standard FastAPI-compatible HTTP 422 errors.
• Built-in HTMX Suite: Native helpers (fragment, hx_trigger, hx_redirect, hx_refresh) and sse_stream / ndjson_stream.
• OpenAPI 3.0 Documentation: Automatic schema generation with Scalar UI, Swagger UI, and ReDoc support at /docs.
• Developer Introspection: CLI tools (des why, des routes, des doctor, des check) to inspect the routing table and runtime health.

CLI Reference

Benchmarks

Overhead measured against an in-memory fixture on localhost using oha (50 concurrent keep-alive connections, median of 5 runs of 5s each, CPython 3.14 on Linux x86_64, 1 worker process).

Framework Tax vs. Raw Server Ceilings (msgspec Encoder)

Measures framework overhead against raw server ceilings when all targets encode JSON per request using msgspec.json.encode with optimize_gc=False. The ~10–15% gap we aim to close represents the unavoidable cost of route matching, request abstraction, and parameter binding over raw protocol sockets:

Default Stack Comparison (Stock Helpers Out-of-the-Box)

Measures out-of-the-box performance using each framework's standard serialization and response helpers:

See perf/compare/ and Why DES? for harness scripts and reproduction details.

Documentation

• 15-Minute Tutorial
• Why DES? (Architecture & Trade-offs)

License & Attribution

Dreaming Electric Sheep is licensed under the MIT License.
Derived from BlackSheep (Copyright (c) Roberto Prevato and contributors). See NOTICE for details.

made with by EduLoboM