Skip to main content

HttpServer

An HTTP / HTTPS server driven from Python.

Register routes (get ... options, route), middleware (use), static files (mount, add_static_file) and the exception / error handlers, then listen (blocking), listen_async or bind_to_any_port. with server: stops it when the block ends.

borrowed (property)​

True for a server another object owns (see _borrowed).

is_running (property)​

True while the server accepts connections.

port (property)​

The port the server listens on (0 before it listens).

__init__​

__init__(self) -> 'None'

Initialize self. See help(type(self)) for accurate signature.

add_static_file​

add_static_file(self, url_path: 'str', file: 'str') -> 'None'

add_static_file(url_path, file) -> None

Serve one file at one exact path.

bind_to_any_port​

bind_to_any_port(self, host: 'str') -> 'int'

bind_to_any_port(host) -> int

listen_async on a port the operating system picks; returns the port (also readable as :attr:port).

group​

group(self, prefix: 'str') -> 'RouteGroup'

group(prefix) -> RouteGroup

A route group under prefix: server.group("/api/v1").use(auth).

listen​

listen(self, host: 'str', port: 'int') -> 'None'

listen(host, port) -> None

Serve on host:port, blocking this thread until stop() is called from another thread; returns after in-flight handlers drain. Raises when the socket cannot bind.

listen_async​

listen_async(self, host: 'str', port: 'int') -> 'None'

listen_async(host, port) -> None

Serve on host:port on the server's own thread; returns once the server accepts connections. Raises when the socket cannot bind.

mount​

mount(self, url_prefix: 'str', dir: 'str') -> 'None'

mount(url_prefix, dir) -> None

Serve the files under directory dir at url_prefix; the content type follows each file's extension (set_mime_type extends the map).

set_default_header​

set_default_header(self, name: 'str', value: 'str') -> 'None'

set_default_header(name, value) -> None

A header appended to every response (repeat for several values).

set_error_handler​

set_error_handler(self, handler: 'ErrorHandler') -> 'None'

set_error_handler(handler) -> None

The page for a response carrying an HTTP error status (a 404, Response.error(N)): handler(request, status) returns a Response (a str or dict return keeps status), or None for the default page. Not called for a handler that raised; that is the exception handler's job.

set_exception_handler​

set_exception_handler(self, handler: 'ExceptionHandler') -> 'None'

set_exception_handler(handler) -> None

The response for a handler that raised: handler(request, what) returns a Response (a str or dict return is sent with status 500), or None for the default 500. what is the raised exception's text; do not echo it to clients. A raise inside this handler is reported through sys.unraisablehook and the default 500 stands.

set_logger​

set_logger(self, logger: 'Logger') -> 'None'

set_logger(logger) -> None

The access logger, called as logger(request, status) after each response. A raise inside it is reported through sys.unraisablehook and never fails the request.

set_max_connections​

set_max_connections(self, max_connections: 'int') -> 'None'

set_max_connections(max_connections) -> None

The concurrent-connection ceiling; 0 means unlimited.

set_mime_type​

set_mime_type(self, extension: 'str', mime: 'str') -> 'None'

set_mime_type(extension, mime) -> None

Map a file extension (".wasm") to a content type for the static routes.

set_payload_max_length​

set_payload_max_length(self, bytes: 'int') -> 'None'

set_payload_max_length(bytes) -> None

The largest request body accepted; a larger one is refused before the handler runs.

set_read_timeout​

set_read_timeout(self, seconds: 'int') -> 'None'

set_read_timeout(seconds) -> None

The per-connection read timeout.

set_tls​

set_tls(self, cert: 'str', key: 'str') -> 'None'

set_tls(cert, key) -> None

Serve HTTPS with this certificate and private key (PEM file paths); every later listen speaks TLS.

set_write_timeout​

set_write_timeout(self, seconds: 'int') -> 'None'

set_write_timeout(seconds) -> None

The per-connection write timeout.

stop​

stop(self) -> 'None'

stop() -> None

Stop accepting connections, let in-flight handlers finish and flush their responses, then return. Safe on a server that is not serving.

wait_until_ready​

wait_until_ready(self, timeout_ms: 'int' = 30000) -> 'None'

wait_until_ready(timeout_ms=30000) -> None

Block until the server accepts connections; raises when timeout_ms elapses first.