API Reference
pyvoy
Directory = Literal['index', 'listing', 'deny']
module-attribute
Behavior when a directory is requested but has no matching index file.
Precompressed = Literal['br', 'gzip', 'zstd']
module-attribute
A precompressed asset variant served in preference order.
HTTPVersion
Mount
dataclass
app
instance-attribute
The application to mount.
path
instance-attribute
The path prefix to mount the application at.
interface = 'asgi'
class-attribute
instance-attribute
The interface type of the application.
PyvoyServer
Programmatic entrypoint to pyvoy.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
app
|
str | Iterable[Mount]
|
The application to serve, either as a string in 'module:attr' format or as an iterable of Mount objects to serve multiple. |
required |
address
|
str
|
The address to listen on. |
'127.0.0.1'
|
port
|
int
|
The port to listen on. |
0
|
tls_port
|
int | None
|
The port to listen on for TLS connections in addition to port. If not specified and tls_key/cert are provided, a single TLS port specified by port will be used. |
None
|
tls_key
|
bytes | PathLike | None
|
The server TLS private key as bytes or a path to a file containing it. |
None
|
tls_cert
|
bytes | PathLike | None
|
The server TLS certificate as bytes or a path to a file containing it. |
None
|
tls_ca_cert
|
bytes | PathLike | None
|
The TLS CA certificate as bytes or a path to a file containing it to use for client certificate validation. |
None
|
tls_enable_http3
|
bool
|
Whether to enable HTTP/3 support for TLS connections. |
True
|
tls_require_client_certificate
|
bool
|
Whether to require client certificates for TLS connections when a CA certificate is specified. |
True
|
interface
|
Interface
|
The interface type of the application ('asgi' or 'wsgi'). |
'asgi'
|
root_path
|
str
|
The root path to mount the application at. |
''
|
log_level
|
LogLevel
|
The log level for Envoy. |
'error'
|
worker_threads
|
int | None
|
The positive number of worker threads to use. |
None
|
lifespan
|
bool | None
|
Whether to enable ASGI lifespan support. Unsets means auto-detect. |
None
|
websockets
|
bool
|
Whether to enable ASGI WebSocket support. WebSockets are handled by the primary application, which must use ASGI. |
False
|
websockets_max_message_size
|
int | None
|
The non-negative maximum WebSocket message size in bytes. Unset uses the default of 64 MiB. |
None
|
websockets_compression
|
bool
|
Whether to enable WebSocket per-message deflate compression. |
True
|
additional_envoy_args
|
list[str] | None
|
Additional command-line arguments to pass to Envoy. |
None
|
env
|
dict[str, str] | None
|
Additional environment variables to pass to the Envoy process. |
None
|
upstreams
|
Iterable[dict[str, Any] | Upstream] | None
|
A list of upstream clusters to add to the Envoy configuration. |
None
|
static_mounts
|
Iterable[StaticMount] | None
|
Static file mounts to serve alongside the application(s). |
None
|
stdout
|
int | IO[bytes] | None
|
Where to redirect the server's stdout. |
DEVNULL
|
stderr
|
int | IO[bytes] | None
|
Where to redirect the server's stderr. |
DEVNULL
|
Raises:
| Type | Description |
|---|---|
TypeError
|
If worker_threads or websockets_max_message_size is not an integer. |
ValueError
|
If worker_threads is not between 1 and sys.maxsize, or websockets_max_message_size is not between 0 and sys.maxsize. |
listener_address
property
The address the server is listening on.
listener_port
property
The port the server is listening on.
listener_port_tls
property
The TLS port the server is listening on, if any.
listener_port_quic
property
The QUIC port the server is listening on, if any.
stdout
property
The server's stdout stream, if capturing is enabled.
stderr
property
The server's stderr stream, if capturing is enabled.
stopped
property
Whether the server has stopped.
start
async
Starts the pyvoy server.
Raises:
| Type | Description |
|---|---|
RuntimeError
|
If the server is already running or starting. |
StartupError
|
If the server fails to start. |
wait
async
Waits for the server process to exit and returns its exit status.
Returns None if the server has not been started.
stop
async
Stops the pyvoy server.
get_envoy_config
Returns the Envoy configuration to use to start the server with pyvoy. The returned dictionary can be serialized to JSON or YAML to pass to Envoy on the command line.
StartupError
Bases: RuntimeError
Raised when the Pyvoy server fails to start properly.
StaticMount
dataclass
A mount that serves static files from the local filesystem.
path
instance-attribute
The URL path prefix to mount at, for example '/assets' or '/'.
The prefix is stripped when resolving files, so '/assets/app.js' mounted at
'/assets' resolves to '
root
instance-attribute
The filesystem directory to serve files from.
index_files = None
class-attribute
instance-attribute
Files attempted in order when a directory is requested. Defaults to ['index.html'].
directory = 'deny'
class-attribute
instance-attribute
Behavior when a directory has no matching index file. Defaults to 'deny'.
precompressed = None
class-attribute
instance-attribute
Precompressed variants to serve when available, in preference order. Defaults to ['br', 'gzip'].
cache_control = None
class-attribute
instance-attribute
The Cache-Control header value to emit for 200/206 responses.
mime_overrides = None
class-attribute
instance-attribute
Extension-to-content-type overrides, for example {'md': 'text/markdown'}.
serve_dotfiles = None
class-attribute
instance-attribute
Whether to serve path segments beginning with a dot. Defaults to False.
options = None
class-attribute
instance-attribute
Additional envoy-files configuration options merged into the generated config.
An escape hatch for knobs not exposed as typed fields (for example 'etag', 'ranges', or 'chunk_size'). Values here take precedence over the typed fields.
TLSConfig
dataclass
key = None
class-attribute
instance-attribute
The TLS key as bytes or a path to a file containing it.
cert = None
class-attribute
instance-attribute
The TLS certificate as bytes or a path to a file containing it.
ca_cert = None
class-attribute
instance-attribute
The TLS CA certificate as bytes or a path to a file containing it.
Upstream
dataclass
name
instance-attribute
The name of the upstream cluster. Must be passed to HTTPTransport.
address
instance-attribute
The address to connect to as host:port.
http_version = None
class-attribute
instance-attribute
The HTTP version to use when connecting to this cluster.
If not specified, will use HTTP/1 for plaintext and ALPN to autodetect for TLS. HTTP/3 requires TLS.
tls = None
class-attribute
instance-attribute
TLS configuration for connecting to this cluster. If not specified, will use plaintext.