Waitress

https://docs.pylonsproject.org/projects/waitress/
Admin
Waitress is a production-quality pure-Python WSGI server with minimal dependencies that runs on Unix...
Tokens:29,871
Snippets:321
Trust Score:10
Update:7 months ago
Show doc for...
Tokens:
Raw
### Waitress Listen Configuration Examples

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

Demonstrates how to configure the 'listen' argument for Waitress, allowing it to bind to multiple host:port combinations. This includes examples for IPv4, IPv6, and wildcard hostnames.

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

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

### Start Waitress with Pre-bound Sockets (Python)

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

This Python code example demonstrates how to start the Waitress server with multiple pre-bound Internet sockets. It defines a simple WSGI application and then creates, binds, and passes these sockets to `waitress.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()
```

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

### Run Waitress from Command Line (Bash)

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

Provides examples of using the `waitress-serve` command-line tool to run a WSGI application. It covers listening on all IPs (IPv4/IPv6) and specific IPv4 addresses.

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

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

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

### Serve WSGI Application with Waitress

Source: https://docs.pylonsproject.org/projects/waitress/en/stable/_sources/differences.rst

Demonstrates the convenience function `waitress.serve` for running a WSGI application. This is a simple and direct way to start a WSGI server instance.

```python
from waitress import serve

# Assume 'app' is your WSGI application object
# For example:
def app(environ, start_response):
    status = '200 OK'
    headers = [('Content-type', 'text/plain')]
    start_response(status, headers)
    return [b"Hello, World!"]

serve(app)
```

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

### Waitress Serve Function API

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

The `waitress.serve` function is the primary entry point for starting a Waitress WSGI server. It accepts a WSGI application and various configuration options to customize the server's behavior.

```APIDOC
## serve Function API

### Description
Starts a Waitress WSGI server to serve the provided WSGI application.

### Method
Function Call

### Endpoint
N/A (Function within a module)

### Parameters
#### Function Arguments
- **app** (WSGI Application) - Required - The WSGI application to serve.
- **listen** (str) - Optional - The host and port to listen on (e.g., '0.0.0.0:8080'). Defaults to '0.0.0.0:8080'.
- **unix_socket** (str) - Optional - Path to a Unix domain socket to listen on.
- **unix_socket_perms** (str) - Optional - Permissions for the Unix domain socket (e.g., '600'). Defaults to '600'.
- **threads** (int) - Optional - The number of worker threads to use. Defaults to 4.
- **url_scheme** (str) - Optional - The URL scheme to use for generated URLs. Defaults to 'http'.
- **url_prefix** (str) - Optional - A prefix to prepend to all URLs.
- **ident** (str) - Optional - An identifier for the server. Defaults to 'waitress'.
- **backlog** (int) - Optional - The maximum number of queued connections. Defaults to 1024.
- **recv_bytes** (int) - Optional - The size of the receive buffer in bytes. Defaults to 8192.
- **send_bytes** (int) - Optional - The size of the send buffer in bytes. Defaults to 1.
- **outbuf_overflow** (int) - Optional - The overflow size for the output buffer. Defaults to 104856.
- **outbuf_high_watermark** (int) - Optional - The high watermark for the output buffer size in bytes. Defaults to 16777216.
- **inbuf_overflow** (int) - Optional - The overflow size for the input buffer. Defaults to 52488.
- **connection_limit** (int) - Optional - The maximum number of concurrent connections. Defaults to 1000.
- **cleanup_interval** (int) - Optional - The interval in seconds for cleaning up idle connections. Defaults to 30.
- **channel_timeout** (int) - Optional - The timeout in seconds for channel inactivity. Defaults to 120.
- **log_socket_errors** (bool) - Optional - Whether to log socket errors. Defaults to True.
- **max_request_header_size** (int) - Optional - The maximum size of the request header in bytes. Defaults to 262144.
- **max_request_body_size** (int) - Optional - The maximum size of the request body in bytes. Defaults to 1073741824.
- **expose_tracebacks** (bool) - Optional - Whether to expose tracebacks in responses. Defaults to False.

### Request Example
```python
from waitress import serve

# Assuming 'my_wsgi_app' is your WSGI application
# serve(my_wsgi_app, host='0.0.0.0', port=8080, threads=10)
```

### Response
#### Success Response
N/A (This function starts a server and typically runs indefinitely until interrupted.)

#### Response Example
N/A
```

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

### Configuring Network Listeners with waitress-serve

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

This example shows various ways to configure network listeners using `waitress-serve`. It includes options for specifying host and port, listening on multiple interfaces using `--listen`, and controlling IPv4/IPv6 support. It also covers Unix domain socket configuration.

```bash
waitress-serve --port=8080 myapp:wsgifunc
```

```bash
waitress-serve --listen=127.0.0.1:8080 --listen=[::1]:8080 myapp:wsgifunc
```

```bash
waitress-serve --unix-socket=/tmp/waitress.sock --unix-socket-perms=666 myapp:wsgifunc
```

```bash
waitress-serve --no-ipv6 myapp:wsgifunc
```

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

### Setting WSGI Environment Variables with waitress-serve

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

This example demonstrates how to set WSGI environment variables using `waitress-serve` options. It shows how to configure the `url_scheme` for the `wsgi.url_scheme` variable and the `url_prefix` for the `SCRIPT_NAME` variable, which affects how `PATH_INFO` is processed.

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

```bash
waitress-serve --url-prefix=/myapp myapp:wsgifunc
```

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

### Tuning Waitress Performance Options

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

This example shows how to tune the performance of the Waitress server using command-line options. It covers setting the number of worker threads (`--threads`), the connection backlog (`--backlog`), and buffer sizes for receiving data (`--recv-bytes`) and output buffering (`--outbuf-overflow`, `--outbuf-high-watermark`).

```bash
waitress-serve --threads=8 --backlog=2048 myapp:wsgifunc
```

```bash
waitress-serve --outbuf-high-watermark=33554432 myapp:wsgifunc
```

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

### Using Boolean Flags with waitress-serve

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

This example illustrates how boolean arguments are handled by `waitress-serve`. It shows how to enable a flag like `--expose-tracebacks` and its negative equivalent `--no-expose-tracebacks`, which correspond to `expose_tracebacks=True` and `expose_tracebacks=False` respectively in the `waitress.serve` function.

```bash
--expose-tracebacks
```

```bash
--no-expose-tracebacks
```

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

### Apache Reverse Proxy Configuration for Waitress

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

Example Apache configuration directives for proxying requests to Waitress. It includes setting 'Host' header and 'X-Forwarded-Proto' for correct URL schemes.

```apache
ProxyPreserveHost On
RequestHeader set X-Forwarded-Proto https

```

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

### Running a WSGI Application with waitress-serve

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

This snippet demonstrates how to use the `waitress-serve` command-line tool to run a WSGI application. It shows the equivalent command-line syntax for the `waitress.serve` Python function, including specifying port and URL scheme. The application is referenced in the format 'module:object'.

```python
import myapp

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

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

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

### Wrap Application with TransLogger in Python

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

This snippet shows how to programmatically wrap a WSGI application with the TransLogger middleware in Python. It explicitly disables the automatic console handler setup for TransLogger.

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

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

### Nginx Reverse Proxy Configuration for Waitress

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

Example Nginx configuration to set the 'Host' header when proxying requests to Waitress. This ensures applications can generate correct URLs.

```nginx
proxy_set_header        Host $host;

```

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

### Configure TransLogger Middleware with PasteDeploy

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

This snippet demonstrates configuring the TransLogger middleware within a PasteDeploy application setup. It defines a filter for TransLogger and includes it in the main pipeline, disabling console handler automation.

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

[pipeline:main]
pipeline = translogger
           wsgiapp
```

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

### Serve WSGI Application with Waitress (Python)

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

Demonstrates how to serve a WSGI application using the waitress.serve function in Python. This function takes the WSGI application callable and various keyword arguments for configuration.

```python
import waitress

# Assuming 'myapp' is a module with a WSGI callable named 'wsgifunc'
# waitress.serve(myapp.wsgifunc, port=8041, url_scheme='https')
```

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

### Python WSGI Application with File Wrapper

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

Example of a Python WSGI application demonstrating the use of wsgi.file_wrapper to serve a JPEG image. It accesses the file wrapper from the WSGI environment and returns it as the application iterator.

```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)
```

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

### Listen on Multiple Sockets with Waitress

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

Demonstrates how to configure Waitress to listen on multiple IP addresses and ports simultaneously. This feature allows for flexible network configuration, supporting both IPv4 and IPv6.

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

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

### Serve WSGI Application with waitress-serve CLI (Shell)

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

Illustrates how to use the waitress-serve command-line interface to serve a WSGI application. It maps function arguments to command-line options, using hyphens instead of underscores.

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

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

### Configure Waitress Console Logging with Python

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

This snippet shows how to configure the Waitress logger to output INFO level messages to the console using Python's logging module. It demonstrates getting the 'waitress' logger and setting its level.

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

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

### Loading WSGI Applications with a Factory Function

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

This snippet demonstrates the use of the `--call` flag with `waitress-serve`. This flag is useful when an application object has a factory method that needs to be called to obtain the WSGI application. The command loads a module and calls a specified factory function.

```bash
waitress-serve --call myapp.mymodule.app.wsgi_factory
```

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

### Serve WSGI App on All IPs and Port 8080 (Python)

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

This Python code snippet demonstrates how to start the Waitress WSGI server to listen on all available IP addresses (IPv4 and IPv6) on port 8080. It requires the `waitress` library and a WSGI application object named `wsgiapp`.

```python
from waitress import serve
serve(wsgiapp, listen='*:8080')
```

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

### Configuring Server Identity and Buffering with waitress-serve

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

This snippet illustrates how to configure the server identity and buffer sizes for the Waitress server via the command line. It includes setting the `ident` for the 'Server' header and tuning buffer-related options like `recv-bytes`, `outbuf-overflow`, `outbuf-high-watermark`, and `inbuf-overflow`.

```bash
waitress-serve --ident=MyServer myapp:wsgifunc
```

```bash
waitress-serve --recv-bytes=4096 --outbuf-overflow=524288 myapp:wsgifunc
```

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

### Serve WSGI App with Default Settings (Python)

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

This Python code snippet illustrates the simplest way to start the Waitress WSGI server, relying on its default settings. By default, Waitress binds to any IPv4 address on port 8080. It requires the `waitress` library and a WSGI application object named `wsgiapp`.

```python
from waitress import serve
serve(wsgiapp)
```

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

### Deploy Waitress on Heroku (Bash)

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

Shows the `Procfile` configuration for serving a WSGI application with Waitress on Heroku. It includes settings for listening on the dynamic port, trusting Heroku's proxy headers, and configuring thread count.

```bash
web: waitress-serve \
    --listen "*:"$PORT \
    --trusted-proxy '*' \
    --trusted-proxy-headers 'x-forwarded-for x-forwarded-proto x-forwarded-port' \
    --log-untrusted-proxy-headers \
    --clear-untrusted-proxy-headers \
    --threads ${WEB_CONCURRENCY:-4} \
    myapp:wsgifunc
```

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

### Run WSGI Application with Waitress Server Instance

Source: https://docs.pylonsproject.org/projects/waitress/en/stable/_sources/differences.rst

Illustrates using the `server.run()` method for deploying a WSGI application with Waitress. This approach offers more control over server configuration.

```python
from waitress import Server

# Assume 'app' is your WSGI application object
# For example:
def app(environ, start_response):
    status = '200 OK'
    headers = [('Content-type', 'text/plain')]
    start_response(status, headers)
    return [b"Hello, World!"]

server = Server(app)
server.run()
```
Tokens:
Raw