Dreaming Electric Sheep (des)

Dreaming Electric Sheep (des) is a Granian RSGI serving stack you pay a framework tax for startup-compiled msgspec binders, automated OpenAPI documentation from those types, and compile-time request pipeline inspection (des why).

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, automated OpenAPI documentation, and clean route handling:

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

app = Application()

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

@get("/hello")
def hello():
    return {"message": "Hello from DES!"}

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

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 measured overhead represents the framework 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