API Reference
pyvoy
ContentEncoding = Literal['gzip', 'br', 'zstd']
module-attribute
A content encoding responses may be compressed with.
Directory = Literal['index', 'listing', 'deny']
module-attribute
Behavior when a directory is requested but has no matching index file.
Loop = Literal['asyncio', 'uvloop', 'winloop', 'zuvloop', 'trio']
module-attribute
An event loop ASGI applications can run on.
Precompressed = Literal['br', 'gzip', 'zstd']
module-attribute
A precompressed asset variant served in preference order.
HTTPVersion
Bases: StrEnum
An enumeration of HTTP versions.
HTTP1 = 'HTTP/1.1'
class-attribute
instance-attribute
HTTP/1.1
HTTP2 = 'HTTP/2'
class-attribute
instance-attribute
HTTP/2
HTTP3 = 'HTTP/3'
class-attribute
instance-attribute
HTTP/3
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
|
loop
|
Loop | None
|
The event loop ASGI applications run on. 'asyncio' is the standard library event loop. Unset uses uvloop, or winloop on Windows. Other event loops must be installed separately. |
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
|
content_encodings
|
Iterable[ContentEncoding] | None
|
The content encodings to compress responses with, in order of preference. Unset or empty disables response compression. When set, applications no longer receive the Accept-Encoding request header so they do not compress responses themselves. |
None
|
enable_otel
|
bool
|
Whether to export Envoy's traces and metrics with OTLP as configured by the standard OTEL_ environment variables, read from the environment the server is started with. Each signal is exported when its OTEL__EXPORTER variable includes 'otlp' or, when unset, an OTLP endpoint is configured. When traces are exported, applications receive the trace context of Envoy's span in the traceparent request header so their instrumentation continues the trace. |
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, websockets_max_message_size is not between 0 and sys.maxsize, or content_encodings contains an unknown or duplicate encoding. When the Envoy config is generated, if enable_otel is set and an OTEL_* environment variable has an invalid value. |
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.