Waitress

A production-quality pure-Python WSGI server designed for high-performance web application serving without external dependencies beyond the Python standard library. Waitress provides comprehensive HTTP/1.0 and HTTP/1.1 protocol support with robust request handling, connection management, and task processing capabilities suitable for both development and production environments.

Package Information

• Package Name: waitress
• Language: Python
• Installation: pip install waitress

Core Imports

import waitress

For serving WSGI applications:

from waitress import serve

For advanced server configuration:

from waitress import serve, create_server
from waitress.adjustments import Adjustments

Basic Usage

from waitress import serve

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 from Waitress!']

# Serve the application on localhost:8080
serve(simple_app)

# With custom configuration
serve(simple_app, host='0.0.0.0', port=8080, threads=6)

Using with web frameworks:

from waitress import serve
from myapp import create_flask_app  # Your Flask/Django/etc app

app = create_flask_app()
serve(app, host='127.0.0.1', port=5000, threads=4)

Architecture

Waitress uses an asynchronous I/O architecture built on Python's asyncore framework:

• Main Server Loop: Handles connection acceptance and management using asyncore
• Thread Pool: Processes WSGI application calls in separate worker threads
• Channel Management: Individual HTTP connections managed by HTTPChannel instances
• Task System: Request processing organized through Task and ThreadedTaskDispatcher
• Buffer Management: Efficient memory and file-based buffer system for request/response data

This design enables high concurrency while maintaining Python's thread safety for WSGI applications.

Capabilities

Server Creation and Control

Primary functions for creating and managing WSGI servers, including the high-level serve() function and lower-level create_server() for advanced use cases.

def serve(app, **kw): ...
def serve_paste(app, global_conf, **kw): ...
def create_server(application, map=None, _start=True, _sock=None, _dispatcher=None, **kw): ...
def profile(cmd, globals, locals, sort_order, callers): ...

Server Management

Configuration and Adjustments

Comprehensive configuration system for tuning server performance, security, and behavior through the Adjustments class and configuration parameters.

class Adjustments:
    def __init__(self, **kw): ...
    @classmethod
    def parse_args(cls, argv): ...  # Returns (kw_dict, args_list)

def asbool(s): ...
def asoctal(s): ...
def aslist(value): ...

Configuration

Command Line Interface

Command-line tools for running WSGI applications directly from the shell, with extensive configuration options and help documentation.

def run(argv=None, _serve=serve): ...
def show_help(stream, name, error=None): ...

Command Line Interface

HTTP Processing and Parsing

Low-level HTTP request parsing, connection management, and protocol handling for custom server implementations and advanced use cases.

class HTTPChannel: ...
class HTTPRequestParser: ...
class ParsingError(Exception): ...

HTTP Processing

Task Management and Threading

Thread pool management and task dispatching system for processing WSGI requests efficiently across multiple worker threads.

class ThreadedTaskDispatcher:
    def set_thread_count(count): ...
    def add_task(task): ...
    def shutdown(): ...

class WSGITask: ...

Task Management

Proxy Headers and Load Balancing

Support for parsing trusted proxy headers (X-Forwarded-For, X-Forwarded-Proto, etc.) when running behind reverse proxies or load balancers.

def proxy_headers_middleware(app, trusted_proxy=None, trusted_proxy_count=None, trusted_proxy_headers=None, clear_untrusted=True, log_untrusted=False): ...
def parse_proxy_headers(environ, trusted_proxy, trusted_proxy_count, trusted_proxy_headers, logger): ...

Proxy Headers

Buffer Management

Efficient memory and file-based buffer system for handling request and response data with automatic overflow management and streaming capabilities.

class FileBasedBuffer:
    def append(self, s): ...
    def get(self, numbytes=-1, skip=False): ...
    def close(self): ...

class BytesIOBasedBuffer(FileBasedBuffer): ...
class TempfileBasedBuffer(FileBasedBuffer): ...
class ReadOnlyFileBasedBuffer(FileBasedBuffer): ...
class OverflowableBuffer: ...

Buffer Management

Error Handling and Utilities

Exception classes, logging utilities, and helper functions for error handling, HTTP date formatting, and server management tasks.

class Error: ...
class BadRequest(Error): ...
class RequestHeaderFieldsTooLarge(BadRequest): ...
class RequestEntityTooLarge(BadRequest): ...
class InternalServerError(Error): ...
class ServerNotImplemented(Error): ...

def build_http_date(when): ...
def parse_http_date(d): ...
def cleanup_unix_socket(path): ...

Error Handling and Utilities