tessl/pypi-waitress

A production-quality pure-Python WSGI server with robust HTTP protocol support and comprehensive configuration options

—

Pending

Overview

Eval results

Files

Command Line Interface

Name: tessl/pypi-waitress
Author: tessl

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

Capabilities

Main Command-Line Entry Point

The primary function for running waitress from the command line, processing arguments and serving applications.

def run(argv=None, _serve=serve):
    """
    Command-line entry point for waitress-serve.
    
    Parameters:
    - argv (list): Command-line arguments (default: sys.argv)
    - _serve (callable): Serve function to use (default: waitress.serve)
    
    Returns:
    int: Exit code (0 for success, non-zero for error)
    
    Raises:
    SystemExit: On argument parsing errors or application import failures
    """

Help Documentation

Functions for displaying comprehensive help information and error details.

def show_help(stream, name, error=None):
    """
    Display complete help text with all available options.
    
    Parameters:
    - stream: Output stream (sys.stdout, sys.stderr, etc.)
    - name (str): Program name for help display
    - error (str): Optional error message to display first
    
    Returns:
    None
    """

def show_exception(stream):
    """
    Display import exception details for troubleshooting.
    
    Parameters:
    - stream: Output stream for error display
    
    Returns:
    None
    """

Console Script Usage

The waitress-serve console script is installed with the package and provides full command-line access.

# Basic usage
waitress-serve myapp:application

# With configuration options
waitress-serve --host=127.0.0.1 --port=8080 --threads=6 myapp:app

# Unix socket (Linux/macOS)
waitress-serve --unix-socket=/tmp/app.sock myapp:app

# Call factory function
waitress-serve --call myapp:create_app

# Display help
waitress-serve --help

Available Command-Line Options

Complete list of supported command-line parameters for server configuration.

# Standard options:
--help                          # Show help information
--call                          # Call the given object to get WSGI app

# Network configuration:
--host=ADDR                     # Hostname/IP to bind (default: 0.0.0.0)
--port=PORT                     # TCP port to bind (default: 8080)
--listen=ip:port                # Listen on specific ip:port (can be repeated)
--[no-]ipv4                     # Toggle IPv4 support
--[no-]ipv6                     # Toggle IPv6 support
--unix-socket=PATH              # Unix domain socket path
--unix-socket-perms=PERMS       # Unix socket permissions (octal, default: 600)

# Performance tuning:
--threads=INT                   # Number of worker threads (default: 4)
--backlog=INT                   # Socket listen backlog (default: 1024)
--recv-bytes=INT                # Socket receive buffer size (default: 8192)
--send-bytes=INT                # Socket send buffer size (default: 18000)
--connection-limit=INT          # Max concurrent connections (default: 100)

# Request limits:
--max-request-header-size=INT   # Max request header size (default: 262144)
--max-request-body-size=INT     # Max request body size (default: 1073741824)

# Timeouts:
--channel-timeout=INT           # Idle connection timeout (default: 120)
--cleanup-interval=INT          # Connection cleanup interval (default: 30)

# Proxy configuration:
--trusted-proxy=IP              # Trusted proxy IP address
--trusted-proxy-count=INT       # Number of trusted proxies
--trusted-proxy-headers=LIST    # Trusted proxy headers (space-separated)

# URL handling:
--url-scheme=STR               # Default URL scheme (default: http)
--url-prefix=STR               # SCRIPT_NAME prefix

# Debugging and logging:
--expose-tracebacks            # Show Python tracebacks to clients
--ident=STR                    # Server identification string (default: waitress)

# Buffer configuration:
--inbuf-overflow=INT           # Input buffer overflow size (default: 512000)
--outbuf-overflow=INT          # Output buffer overflow size (default: 1048576)

Usage Examples

Common command-line usage patterns for different deployment scenarios.

Basic Application Serving

# Serve a Flask app
waitress-serve --host=127.0.0.1 --port=5000 myflaskapp:app

# Serve a Django app (requires DJANGO_SETTINGS_MODULE)
export DJANGO_SETTINGS_MODULE=myproject.settings
waitress-serve --port=8000 myproject.wsgi:application

# Serve with app factory
waitress-serve --call --host=0.0.0.0 --port=8080 myapp:create_app

Performance Configuration

# High-performance setup
waitress-serve \
  --threads=8 \
  --connection-limit=1000 \
  --recv-bytes=16384 \
  --backlog=2048 \
  myapp:application

# Development setup with debugging
waitress-serve \
  --host=127.0.0.1 \
  --port=5000 \
  --threads=1 \
  --expose-tracebacks \
  myapp:app

Proxy and Load Balancer Setup

# Behind nginx reverse proxy
waitress-serve \
  --host=127.0.0.1 \
  --port=8080 \
  --trusted-proxy=127.0.0.1 \
  --trusted-proxy-headers="x-forwarded-for x-forwarded-proto" \
  --url-scheme=https \
  myapp:app

# Multiple proxy layers (e.g., Cloudflare + nginx)
waitress-serve \
  --trusted-proxy-count=2 \
  --trusted-proxy-headers="x-forwarded-for x-forwarded-proto x-real-ip" \
  myapp:app

Unix Socket Configuration

# Unix socket with custom permissions (Linux/macOS)
waitress-serve \
  --unix-socket=/var/run/myapp.sock \
  --unix-socket-perms=666 \
  myapp:app

# Socket with nginx configuration
waitress-serve \
  --unix-socket=/tmp/myapp.sock \
  --unix-socket-perms=660 \
  myapp:app

Security-Focused Configuration

# Restricted for security
waitress-serve \
  --host=127.0.0.1 \
  --max-request-header-size=65536 \
  --max-request-body-size=10485760 \
  --channel-timeout=60 \
  --connection-limit=50 \
  myapp:app

Module and Application Specification

The command-line interface supports flexible module and application specification.

# Module:attribute format
waitress-serve mypackage.mymodule:myapp

# Package with __main__ module
waitress-serve mypackage

# Nested attribute access
waitress-serve mypackage.submodule:factory().wsgi_app

# With --call flag for factory functions
waitress-serve --call mypackage:create_application

# Django integration
waitress-serve django_project.wsgi:application

Error Handling

The command-line interface provides helpful error messages for common issues.

# Import errors show detailed traceback
waitress-serve nonexistent:app
# Shows import error with suggestions

# Invalid arguments show help
waitress-serve --invalid-option
# Shows error and displays help

# Module not found
waitress-serve badmodule:app
# Shows import error with troubleshooting info

Integration with Process Managers

Waitress command-line interface works well with process managers and deployment tools.

# Supervisor configuration
[program:myapp]
command=waitress-serve --host=127.0.0.1 --port=8080 myapp:app
directory=/path/to/app
user=www-data
autostart=true
autorestart=true

# systemd service file
[Unit]
Description=My WSGI App
After=network.target

[Service]
Type=exec
User=www-data
WorkingDirectory=/path/to/app
ExecStart=/usr/local/bin/waitress-serve --host=127.0.0.1 --port=8080 myapp:app
Restart=always

[Install]
WantedBy=multi-user.target

Install with Tessl CLI