Skip to content

API Reference

pyvoy.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 number of worker threads to use.

 None
lifespan bool | None

Whether to enable ASGI lifespan support. Unsets means auto-detect.

 None
additional_envoy_args list[str] | None

Additional command-line arguments to pass to Envoy.

 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

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
StartupError

If the server fails to start.

wait async

Waits for the server to finish shutting down. May be necessary if stopping in a separate task.

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.

pyvoy.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.