0
# Waitress
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: waitress
7
- **Language**: Python
8
- **Installation**: `pip install waitress`
9

10
## Core Imports
11

12
```python
13
import waitress
14
```
15

16
For serving WSGI applications:
17

18
```python
19
from waitress import serve
20
```
21

22
For advanced server configuration:
23

24
```python
25
from waitress import serve, create_server
26
from waitress.adjustments import Adjustments
27
```
28

29
## Basic Usage
30

31
```python
32
from waitress import serve
33

34
def simple_app(environ, start_response):
35
    """A simple WSGI application"""
36
    status = '200 OK'
37
    headers = [('Content-type', 'text/plain')]
38
    start_response(status, headers)
39
    return [b'Hello from Waitress!']
40

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

44
# With custom configuration
45
serve(simple_app, host='0.0.0.0', port=8080, threads=6)
46
```
47

48
Using with web frameworks:
49

50
```python
51
from waitress import serve
52
from myapp import create_flask_app  # Your Flask/Django/etc app
53

54
app = create_flask_app()
55
serve(app, host='127.0.0.1', port=5000, threads=4)
56
```
57

58
## Architecture
59

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

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

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

70
## Capabilities
71

72
### Server Creation and Control
73

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

76
```python { .api }
77
def serve(app, **kw): ...
78
def serve_paste(app, global_conf, **kw): ...
79
def create_server(application, map=None, _start=True, _sock=None, _dispatcher=None, **kw): ...
80
def profile(cmd, globals, locals, sort_order, callers): ...
81
```
82

83
[Server Management](./server-management.md)
84

85
### Configuration and Adjustments
86

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

89
```python { .api }
90
class Adjustments:
91
    def __init__(self, **kw): ...
92
    @classmethod
93
    def parse_args(cls, argv): ...  # Returns (kw_dict, args_list)
94

95
def asbool(s): ...
96
def asoctal(s): ...
97
def aslist(value): ...
98
```
99

100
[Configuration](./configuration.md)
101

102
### Command Line Interface
103

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

106
```python { .api }
107
def run(argv=None, _serve=serve): ...
108
def show_help(stream, name, error=None): ...
109
```
110

111
[Command Line Interface](./command-line.md)
112

113
### HTTP Processing and Parsing
114

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

117
```python { .api }
118
class HTTPChannel: ...
119
class HTTPRequestParser: ...
120
class ParsingError(Exception): ...
121
```
122

123
[HTTP Processing](./http-processing.md)
124

125
### Task Management and Threading
126

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

129
```python { .api }
130
class ThreadedTaskDispatcher:
131
    def set_thread_count(count): ...
132
    def add_task(task): ...
133
    def shutdown(): ...
134

135
class WSGITask: ...
136
```
137

138
[Task Management](./task-management.md)
139

140
### Proxy Headers and Load Balancing
141

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

144
```python { .api }
145
def proxy_headers_middleware(app, trusted_proxy=None, trusted_proxy_count=None, trusted_proxy_headers=None, clear_untrusted=True, log_untrusted=False): ...
146
def parse_proxy_headers(environ, trusted_proxy, trusted_proxy_count, trusted_proxy_headers, logger): ...
147
```
148

149
[Proxy Headers](./proxy-headers.md)
150

151
### Buffer Management
152

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

155
```python { .api }
156
class FileBasedBuffer:
157
    def append(self, s): ...
158
    def get(self, numbytes=-1, skip=False): ...
159
    def close(self): ...
160

161
class BytesIOBasedBuffer(FileBasedBuffer): ...
162
class TempfileBasedBuffer(FileBasedBuffer): ...
163
class ReadOnlyFileBasedBuffer(FileBasedBuffer): ...
164
class OverflowableBuffer: ...
165
```
166

167
[Buffer Management](./buffer-management.md)
168

169
### Error Handling and Utilities
170

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

173
```python { .api }
174
class Error: ...
175
class BadRequest(Error): ...
176
class RequestHeaderFieldsTooLarge(BadRequest): ...
177
class RequestEntityTooLarge(BadRequest): ...
178
class InternalServerError(Error): ...
179
class ServerNotImplemented(Error): ...
180

181
def build_http_date(when): ...
182
def parse_http_date(d): ...
183
def cleanup_unix_socket(path): ...
184
```
185

186
[Error Handling and Utilities](./error-handling.md)