Waitress

https://docs.pylonsproject.org/projects/waitress/en/latest/
Admin
Waitress is a production-quality, pure-Python WSGI server with no external dependencies designed to...
Tokens:39,193
Snippets:384
Trust Score:10
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### waitress-serve command line examples

Source: https://docs.pylonsproject.org/projects/waitress/en/latest/usage.html

Command line runner examples: listen on both IPv4 and IPv6 on port 8041, or listen on only IPv4 on port 8041.

```bash
# Listen on both IPv4 and IPv6 on port 8041
waitress-serve --listen=*:8041 myapp:wsgifunc

# Listen on only IPv4 on port 8041
waitress-serve --port=8041 myapp:wsgifunc

```

--------------------------------

### --listen option example

Source: https://docs.pylonsproject.org/projects/waitress/en/latest/runner.html

Example of the --listen option used multiple times to listen on multiple sockets. A wildcard hostname binds to both IPv4 and IPv6 depending on their enabled state.

```text
--listen=127.0.0.1:8080 --listen=[::1]:8080 --listen=*:8080
```

--------------------------------

### waitress-serve --listen examples

Source: https://docs.pylonsproject.org/projects/waitress/en/latest/_sources/runner.rst.txt

Examples of the --listen option for waitress-serve. It can be used multiple times to listen on multiple sockets, and a wildcard hostname binds to both IPv4/IPv6 depending on their enabled state.

```shell
--listen=127.0.0.1:8080
--listen=[::1]:8080
--listen=*:8080
```

--------------------------------

### Waitress: Use url_prefix

Source: https://docs.pylonsproject.org/projects/waitress/en/latest/_sources/reverse-proxy.rst.txt

Start Waitress with a URL prefix '/foo' so downstream applications that respect SCRIPT_NAME generate URLs with this prefix.

```python
from waitress import serve
serve(wsgiapp, listen='0.0.0.0:8080', url_prefix='/foo')
```

--------------------------------

### listen argument examples

Source: https://docs.pylonsproject.org/projects/waitress/en/latest/_sources/arguments.rst.txt

Shows how to specify the listen argument as a quoted, space-delimited list of host:port combinations. A wildcard for the hostname binds to both IPv4/IPv6 depending on their enabled state. IPv6 addresses must be surrounded by brackets.

```python
listen="127.0.0.1:8080 [::1]:8080"
listen="*:8080 *:6543"
```

--------------------------------

### waitress-serve command with hyphens

Source: https://docs.pylonsproject.org/projects/waitress/en/latest/runner.html

Equivalent command-line invocation using hyphens for the same arguments as the Python example above.

```bash
waitress-serve --port=8041 --url-scheme=https myapp:wsgifunc
```

--------------------------------

### Wrap app with TransLogger in Python

Source: https://docs.pylonsproject.org/projects/waitress/en/latest/logging.html

Equivalent to the PasteDeploy pipeline: wrap your app in a TransLogger instance and serve it with Waitress. Disables the automatic console handler setup because logging handlers are already configured.

```python
from mypackage import wsgiapp
from waitress import serve
from paste.translogger import TransLogger
serve(TransLogger(wsgiapp, setup_console_handler=False))

```

--------------------------------

### waitress.serve(app, listen='0.0.0.0:8080', unix_socket=None, unix_socket_perms='600', threads=4, url_scheme='http', url_prefix='', ident='waitress', backlog=1024, recv_bytes=8192, send_bytes=1, outbuf_overflow=104856, outbuf_high_watermark=16777216, inbuf_overflow=52488, connection_limit=1000, cleanup_interval=30, channel_timeout=120, log_socket_errors=True, max_request_header_size=262144, max_request_body_size=1073741824, expose_tracebacks=False)

Source: https://docs.pylonsproject.org/projects/waitress/en/latest/_sources/api.rst.txt

The serve function is the main entry point for running a WSGI application with Waitress. It starts the server and blocks until the server is shut down. The function accepts an application object and various configuration parameters to control the server's behavior.

```APIDOC
## waitress.serve(app, listen='0.0.0.0:8080', unix_socket=None, unix_socket_perms='600', threads=4, url_scheme='http', url_prefix='', ident='waitress', backlog=1024, recv_bytes=8192, send_bytes=1, outbuf_overflow=104856, outbuf_high_watermark=16777216, inbuf_overflow=52488, connection_limit=1000, cleanup_interval=30, channel_timeout=120, log_socket_errors=True, max_request_header_size=262144, max_request_body_size=1073741824, expose_tracebacks=False)

### Description
Starts a Waitress WSGI server to serve the given WSGI application. This function blocks until the server is shut down.

### Parameters
- **app** (WSGI application) - Required - The WSGI application to serve.
- **listen** (str) - Optional - The host:port to listen on. Default: '0.0.0.0:8080'.
- **unix_socket** (str) - Optional - Path to a Unix socket to listen on. Default: None.
- **unix_socket_perms** (str) - Optional - Permissions for the Unix socket. Default: '600'.
- **threads** (int) - Optional - Number of threads to use. Default: 4.
- **url_scheme** (str) - Optional - The URL scheme to use. Default: 'http'.
- **url_prefix** (str) - Optional - A URL prefix to use. Default: ''.
- **ident** (str) - Optional - The server identification string. Default: 'waitress'.
- **backlog** (int) - Optional - The backlog for the listening socket. Default: 1024.
- **recv_bytes** (int) - Optional - The number of bytes to receive at a time. Default: 8192.
- **send_bytes** (int) - Optional - The number of bytes to send at a time. Default: 1.
- **outbuf_overflow** (int) - Optional - The output buffer overflow size. Default: 104856.
- **outbuf_high_watermark** (int) - Optional - The output buffer high watermark. Default: 16777216.
- **inbuf_overflow** (int) - Optional - The input buffer overflow size. Default: 52488.
- **connection_limit** (int) - Optional - The maximum number of simultaneous connections. Default: 1000.
- **cleanup_interval** (int) - Optional - The interval for cleanup tasks. Default: 30.
- **channel_timeout** (int) - Optional - The timeout for channels. Default: 120.
- **log_socket_errors** (bool) - Optional - Whether to log socket errors. Default: True.
- **max_request_header_size** (int) - Optional - The maximum size of request headers. Default: 262144.
- **max_request_body_size** (int) - Optional - The maximum size of the request body. Default: 1073741824.
- **expose_tracebacks** (bool) - Optional - Whether to expose tracebacks in error responses. Default: False.

### Returns
None. The function blocks until the server is shut down.
```

--------------------------------

### Start waitress with two pre-bound sockets using waitress.serve(sockets=...)

Source: https://docs.pylonsproject.org/projects/waitress/en/latest/_sources/socket-activation.rst.txt

Creates two INET stream sockets, binds them to 127.0.0.1 on ports 8080 and 9090, and passes them to waitress.serve() via the 'sockets' parameter. Sockets are closed after serve() returns. This is the pattern for manual socket activation; init systems provide bound sockets that are passed directly to serve().

```python
import socket
import waitress


def app(environ, start_response):
    content_length = environ.get('CONTENT_LENGTH', None)
    if content_length is not None:
        content_length = int(content_length)
    body = environ['wsgi.input'].read(content_length)
    content_length = str(len(body))
    start_response(
        '200 OK',
        [('Content-Length', content_length), ('Content-Type', 'text/plain')]
    )
    return [body]


if __name__ == '__main__':
    sockets = [
        socket.socket(socket.AF_INET, socket.SOCK_STREAM),
        socket.socket(socket.AF_INET, socket.SOCK_STREAM)]
    sockets[0].bind(('127.0.0.1', 8080))
    sockets[1].bind(('127.0.0.1', 9090))
    waitress.serve(app, sockets=sockets)
    for socket in sockets:
        socket.close()
```

--------------------------------

### Equivalent waitress.serve and waitress-serve invocations

Source: https://docs.pylonsproject.org/projects/waitress/en/latest/_sources/runner.rst.txt

Shows the equivalent ways to start a WSGI application with waitress: the Python function call and two waitress-serve command-line invocations. The first uses the waitress.serve function with underscore arguments, while the command-line versions use hyphens and either a positional MODULE:OBJECT or the --app flag.

```python
import myapp

waitress.serve(myapp.wsgifunc, port=8041, url_scheme='https')
```

```shell
waitress-serve --port=8041 --url-scheme=https myapp:wsgifunc
```

```shell
waitress-serve --port=8041 --url-scheme=https --app=myapp:wsgifunc
```

--------------------------------

### WSGI application using environ['wsgi.file_wrapper']

Source: https://docs.pylonsproject.org/projects/waitress/en/latest/_sources/filewrapper.rst.txt

Example WSGI application that returns a file wrapper for serving a file. The wrapper is accessed via environ['wsgi.file_wrapper'] and must be returned as the app_iter. The file-like object must support read() with optional size hint and return bytes; block_size is optional (default 32768).

```python
import os

here = os.path.dirname(os.path.abspath(__file__))

def myapp(environ, start_response):
    f = open(os.path.join(here, 'myphoto.jpg'), 'rb')
    headers = [('Content-Type', 'image/jpeg')]
    start_response(
        '200 OK',
        headers
        )
    return environ['wsgi.file_wrapper'](f, 32768)
```

--------------------------------

### Serve with multiple listen sockets in Waitress 1.0.0

Source: https://docs.pylonsproject.org/projects/waitress/en/latest/index.html

Waitress 1.0.0 supports listening on multiple sockets, including IPv4 and IPv6, by passing a space-delineated list to the listen parameter. The example binds to IPv4 (0.0.0.0:8080), IPv6 ([::]:9090), and all interfaces (*:6543).

```python
from waitress import serve
serve(wsgiapp, listen='0.0.0.0:8080 [::]:9090 *:6543')

```

--------------------------------

### serve()

Source: https://docs.pylonsproject.org/projects/waitress/en/latest/api.html

Documentation for the serve() function, the main entry point for running a WSGI application with Waitress.

```APIDOC
## serve(app, listen='0.0.0.0:8080', unix_socket=None, unix_socket_perms='600', threads=4, url_scheme='http', url_prefix='', ident='waitress', backlog=1024, recv_bytes=8192, send_bytes=1, outbuf_overflow=104856, outbuf_high_watermark=16777216, inbuf_overflow=52488, connection_limit=1000, cleanup_interval=30, channel_timeout=120, log_socket_errors=True, max_request_header_size=262144, max_request_body_size=1073741824, expose_tracebacks=False)

### Description
Serves the given WSGI application using the Waitress WSGI server. This is the primary entry point for running a WSGI application with Waitress.

### Method
Function call

### Endpoint
serve()

### Parameters
- **app** (WSGI application) - Required - The WSGI application to serve.
- **listen** (string) - Optional - The host:port to listen on. Default: '0.0.0.0:8080'.
- **unix_socket** (string) - Optional - Path to a Unix socket to listen on. Default: None.
- **unix_socket_perms** (string) - Optional - Permissions for the Unix socket. Default: '600'.
- **threads** (int) - Optional - Number of threads to use. Default: 4.
- **url_scheme** (string) - Optional - The URL scheme to use. Default: 'http'.
- **url_prefix** (string) - Optional - URL prefix for the application. Default: ''.
- **ident** (string) - Optional - Server identity string. Default: 'waitress'.
- **backlog** (int) - Optional - Backlog size for the listening socket. Default: 1024.
- **recv_bytes** (int) - Optional - Number of bytes to receive at a time. Default: 8192.
- **send_bytes** (int) - Optional - Number of bytes to send at a time. Default: 1.
- **outbuf_overflow** (int) - Optional - Overflow size for output buffer. Default: 104856.
- **outbuf_high_watermark** (int) - Optional - High watermark for output buffer. Default: 16777216.
- **inbuf_overflow** (int) - Optional - Overflow size for input buffer. Default: 52488.
- **connection_limit** (int) - Optional - Maximum number of simultaneous connections. Default: 1000.
- **cleanup_interval** (int) - Optional - Interval for cleanup tasks. Default: 30.
- **channel_timeout** (int) - Optional - Timeout for channels. Default: 120.
- **log_socket_errors** (bool) - Optional - Whether to log socket errors. Default: True.
- **max_request_header_size** (int) - Optional - Maximum size of request headers. Default: 262144.
- **max_request_body_size** (int) - Optional - Maximum size of request body. Default: 1073741824.
- **expose_tracebacks** (bool) - Optional - Whether to expose tracebacks in error responses. Default: False.

### Request Example
No request body is applicable for this function call.

### Response
#### Success Response
No return value is documented. The function starts the server and blocks.

#### Response Example
No response body is applicable.
```

--------------------------------

### Console output with TransLogger filter

Source: https://docs.pylonsproject.org/projects/waitress/en/latest/logging.html

Example console output when requesting a page with the TransLogger filter in place. Shows the wsgi logger propagating messages to the root logger and the console.

```text
00:50:53,694 INFO [wsgiapp] Returning: Hello World!
                  (content-type: text/plain)
00:50:53,695 INFO [wsgi] 192.168.1.111 - - [11/Aug/2011:20:09:33 -0700] "GET /hello
HTTP/1.1" 404 - "-"
"Mozilla/5.0 (Macintosh; U; Intel Mac OS X; en-US; rv:1.8.1.6) Gecko/20070725
Firefox/2.0.0.6"

```

--------------------------------

### Base PasteDeploy Configuration for WSGI App and Waitress

Source: https://docs.pylonsproject.org/projects/waitress/en/latest/_sources/logging.rst.txt

Base PasteDeploy configuration with a WSGI application and Waitress server. This is the starting point for adding a TransLogger filter to log web traffic.

```ini
[app:wsgiapp]
use = egg:mypackage#wsgiapp

[server:main]
use = egg:waitress#main
host = 127.0.0.1
port = 8080
```

--------------------------------

### Serve a WSGI app with url_prefix

Source: https://docs.pylonsproject.org/projects/waitress/en/latest/reverse-proxy.html

Sets the `url_prefix` to '/foo' when serving a WSGI application. This causes the WSGI `SCRIPT_NAME` to be '/foo' (minus trailing slashes) and strips the prefix from `PATH_INFO` for requests that start with it.

```python
from waitress import serve
serve(wsgiapp, listen='0.0.0.0:8080', url_prefix='/foo')

```

--------------------------------

### Using --app flag to specify application

Source: https://docs.pylonsproject.org/projects/waitress/en/latest/runner.html

Shows how to use the --app flag to explicitly specify the application object.

```bash
waitress-serve --port=8041 --url-scheme=https --app=myapp:wsgifunc
```

--------------------------------

### PasteDeploy configuration with listen

Source: https://docs.pylonsproject.org/projects/waitress/en/latest/_sources/usage.rst.txt

Entry point for PasteDeploy (egg:waitress#main) that lets you use Waitress's WSGI gateway from a configuration file.

```ini
[server:main]
use = egg:waitress#main
listen = 127.0.0.1:8080
```

--------------------------------

### Waitress: Use https url_scheme

Source: https://docs.pylonsproject.org/projects/waitress/en/latest/_sources/reverse-proxy.rst.txt

Start Waitress with the https url scheme, so all generated URLs use https. Useful when the proxy accepts HTTPS and the backend does not need to detect the scheme per request.

```python
from waitress import serve
serve(wsgiapp, listen='0.0.0.0:8080', url_scheme='https')
```

--------------------------------

### Configure Waitress logger level with Python logging API

Source: https://docs.pylonsproject.org/projects/waitress/en/latest/logging.html

Sets the logging level for the 'waitress' logger to INFO using the Python logging module. This must be done before the server starts to take effect.

```python
import logging
logger = logging.getLogger('waitress')
logger.setLevel(logging.INFO)

```

--------------------------------

### waitress-serve usage syntax

Source: https://docs.pylonsproject.org/projects/waitress/en/latest/_sources/runner.rst.txt

Usage line for the waitress-serve command. Shows the general syntax with optional options and a positional MODULE:OBJECT argument.

```shell
waitress-serve [OPTS] [MODULE:OBJECT]
```

--------------------------------

### Configure TransLogger with PasteDeploy pipeline

Source: https://docs.pylonsproject.org/projects/waitress/en/latest/logging.html

Configure a WSGI pipeline with TransLogger and your app using PasteDeploy .ini syntax. The first block shows the existing app and server configuration; the second adds the translogger filter and pipeline, disabling the console handler setup.

```ini
[app:wsgiapp]
use = egg:mypackage#wsgiapp

[server:main]
use = egg:waitress#main
host = 127.0.0.1
port = 8080

```

```ini
[filter:translogger]
use = egg:Paste#translogger
setup_console_handler = False

[pipeline:main]
pipeline = translogger
           wsgiapp

```
Tokens:
Raw