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)