bengal-pounce 0.2.1

A free-threading-native ASGI server for Python 3.14t

=^..^= Pounce

A free-threading-native ASGI server for Python 3.14t.

import pounce

pounce.run("myapp:app")

---

What is Pounce?

Pounce is a free-threading-native ASGI server for Python 3.14t. N worker threads share one interpreter, one copy of your app, one set of frozen config. On GIL builds, it falls back to multi-process automatically.

What's good about it:

• Free-threading native — Threads, not processes. One interpreter, N event loops, shared immutable state. Zero synchronization for immutable data.
• 2026-native features — Stdlib compression.zstd (PEP 784) for zero-dependency zstd content-encoding. Server-Timing headers for built-in observability.
• Streaming-first — Chunked HTML, event streams, AI token delivery. Body chunks sent immediately to socket, never buffered.

---

Installation

pip install bengal-pounce

Requires Python 3.14+

Optional extras:

pip install bengal-pounce[fast]   # httptools C-accelerated HTTP/1.1
pip install bengal-pounce[h2]     # HTTP/2 stream multiplexing
pip install bengal-pounce[ws]     # WebSocket via wsproto
pip install bengal-pounce[tls]    # TLS with truststore
pip install bengal-pounce[h3]     # HTTP/3 (QUIC/UDP, requires TLS)
pip install bengal-pounce[full]   # Everything above (except httptools)

---

Quick Start

Usage	Command
Programmatic	pounce.run("myapp:app")
CLI	pounce myapp:app
Multi-worker	pounce myapp:app --workers 4
TLS	pounce myapp:app --ssl-certfile cert.pem --ssl-keyfile key.pem
HTTP/3	pounce myapp:app --http3 --ssl-certfile cert.pem --ssl-keyfile key.pem
Dev reload	pounce myapp:app --reload
App factory	pounce myapp:create_app()

---

Features

Feature	Description	Docs
HTTP/1.1	h11 (pure Python) or httptools (C-accelerated)	HTTP/1.1 →
HTTP/2	Stream multiplexing via h2	HTTP/2 →
HTTP/3	QUIC/UDP via aioquic (requires TLS)	—
WebSocket	Full RFC 6455 via wsproto (including WS over H2)	WebSocket →
Static Files	Zero-copy sendfile, pre-compressed, ETags	Static Files →
Middleware	ASGI3 middleware stack support	Middleware →
OpenTelemetry	Native distributed tracing (OTLP)	OpenTelemetry →
Lifecycle Logging	Structured JSON event logging	Logging →
Graceful Shutdown	Kubernetes-ready connection draining	Shutdown →
Dev Error Pages	Rich tracebacks with syntax highlighting	Errors →
TLS	SSL with truststore integration	TLS →
Compression	zstd (stdlib PEP 784) + gzip + WS compression	Compression →
Workers	Auto-detect: threads (3.14t) or processes (GIL)	Workers →
Auto Reload	Graceful restart on file changes	Reload →

📚 Full documentation: lbliii.github.io/pounce | Complete Feature List →

---

Usage

Programmatic Configuration — Full control from Python

import pounce

pounce.run(
    "myapp:app",
    host="0.0.0.0",
    port=8000,
    workers=4,
)

How It Works — Adaptive worker model

On Python 3.14t (free-threading): workers are threads. One process, N threads, each with its own asyncio event loop. Shared memory, no fork overhead, no IPC.

On GIL builds: workers are processes. Same API, same config. The supervisor detects the runtime via sys._is_gil_enabled() and adapts automatically.

A request flows through: socket accept -> protocol parser (h11 or httptools) -> ASGI scope construction -> app(scope, receive, send) -> response serialization -> socket write.

Protocol Extras — Install only what you need

Protocol	Backend	Install
HTTP/1.1	h11 (pure Python, default)	built-in
HTTP/1.1	httptools (C-accelerated)	pounce[fast]
HTTP/2	h2 (stream multiplexing, priority signals)	pounce[h2]
WebSocket	wsproto (including WS over H2)	pounce[ws]
TLS	stdlib ssl + truststore	pounce[tls]
All	Everything above (except httptools)	pounce[full]

Compression uses Python 3.14's stdlib compression.zstd — zero external dependencies.

---

Key Ideas

• Free-threading first. Threads, not processes. One interpreter, N event loops, shared immutable state. On GIL builds, falls back to multi-process automatically.
• Pure Python. No Rust, no C extensions in the server core. Debuggable, hackable, readable.
• Typed end-to-end. Frozen config, typed ASGI definitions, zero type: ignore comments.
• One dependency. h11 for HTTP/1.1 parsing. Everything else is optional.
• Observable. Structured lifecycle events — frozen dataclasses with nanosecond timestamps. Zero overhead when no collector is attached.
• Chirp companion. Built to serve Chirp apps natively, but works with any ASGI framework.

---

Documentation

📚 lbliii.github.io/pounce

Section	Description
Get Started	Installation and quickstart
Protocols	HTTP/1.1, HTTP/2, WebSocket
Configuration	Server config, TLS, CLI
Deployment	Workers, compression, production
Extending	ASGI bridge, custom protocols
Tutorials	Uvicorn migration guide
Troubleshooting	Common issues and fixes
Reference	API documentation
About	Architecture, performance, FAQ

---

Development

git clone https://github.com/lbliii/pounce.git
cd pounce
uv sync --group dev
pytest

---

The Bengal Ecosystem

A structured reactive stack — every layer written in pure Python for 3.14t free-threading.

ᓚᘏᗢ	Bengal	Static site generator	Docs
∿∿	Purr	Content runtime	—
⌁⌁	Chirp	Web framework	Docs
=^..^=	Pounce	ASGI server ← You are here	Docs
)彡	Kida	Template engine	Docs
ฅᨐฅ	Patitas	Markdown parser	Docs
⌾⌾⌾	Rosettes	Syntax highlighter	Docs

Python-native. Free-threading ready. No npm required.

---

License

MIT