Cheroot HTTP Server

11.1.2 · active · verified Sat Apr 11

Cheroot is a high-performance, pure-Python HTTP server used by the CherryPy web framework, but it can also be used as a standalone WSGI server. It provides a robust and efficient way to serve web applications. The library is actively maintained, with the current version being 11.1.2, and aims for high stability and performance.

Warnings

gotcha When serving WSGI applications, ensure that response status and headers adhere to PEP 3333. For Python 3, these must be `str` type but restricted to Latin-1 code points, not arbitrary Unicode.
Fix: Ensure WSGI application returns `str` for status and headers with only Latin-1 compatible characters, and `bytes` for the body.
gotcha The `start_response` callable in a WSGI application must not transmit headers immediately. It should store them, and the server (Cheroot) will transmit them only after the first non-empty iterable yielded by the application or explicit `write()` call.
Fix: Follow the WSGI specification (PEP 3333) for `start_response` implementation in your application.
gotcha By default, if the host specification is omitted during server instantiation, Cheroot will listen on all IPv4 interfaces (`0.0.0.0`). The default port, if not specified, is `8080`. Always explicitly configure the bind address for production environments.
Fix: Always pass a `bind_addr` tuple like `('127.0.0.1', 8080)` or `('0.0.0.0', 80)` to the `Server` constructor, or use environment variables for flexible deployment.

Install

pip install cheroot Install stable version
pip install cheroot[zope] Install with optional zope.interface dependency

Imports

Server
```
from cheroot.wsgi import Server
```
The core WSGI Server class is located within the `cheroot.wsgi` module.
PathInfoDispatcher
```
from cheroot.wsgi import PathInfoDispatcher
```
Used for routing multiple WSGI applications based on URL path.

Quickstart

This quickstart demonstrates how to set up a basic Cheroot WSGI server with two different applications dispatched by `PathInfoDispatcher`. It listens on a configurable host and port (defaulting to `127.0.0.1:8070`), and handles incoming requests with a simple 'Hello, Cheroot!' response or a delayed response.

import os
import time
from cheroot.wsgi import Server, PathInfoDispatcher


def simple_app(environ, start_response):
    """A simple WSGI application."""
    status = '200 OK'
    headers = [('Content-type', 'text/plain')]
    start_response(status, headers)
    return [b'Hello, Cheroot!\n']

def delayed_app(environ, start_response):
    """An application with a delay to demonstrate concurrency."""
    time.sleep(2) # Simulate work
    status = '200 OK'
    headers = [('Content-type', 'text/plain')]
    start_response(status, headers)
    return [b'Hello after 2 seconds!\n']

# Map paths to WSGI applications
path_map = {
    '/': simple_app,
    '/delay': delayed_app,
}
dispatcher = PathInfoDispatcher(path_map)

# Configure the server
# Default host is 0.0.0.0, default port is 8080 if not specified
# Using 127.0.0.1 and a common testing port here
host = os.environ.get('CHERoot_HOST', '127.0.0.1')
port = int(os.environ.get('CHERoot_PORT', 8070))

server = Server((host, port), dispatcher)

print(f"Cheroot server starting on http://{host}:{port}/")
print("Access http://localhost:8070/ and http://localhost:8070/delay")
print("Press Ctrl+C to stop...")

try:
    server.start()
except KeyboardInterrupt:
    server.stop()
    print("Cheroot server stopped.")

view raw JSON →