vinegar.http.server

HTTP server component of Vinegar.

class vinegar.http.server.HttpRequestHandler

Interface for a request handler. A request handler should be derived from this class and implement the can_handle and handle methods.

The can_handle and handle methods are separate, because a request handler should only decided whether it can handle a request based on the requested filename. If it later finds that it actually cannot handle the request due to an unsupport HTTP method, it should simply signal an error.

A request handler can also implement prepare_context. In this case, prepare_context is called before calling can_handle and the object returned by it is passed to can_handle and handle. This is useful when both function need to do some processing on the filename or client address. This processing can be implemented in prepare_context and passed to the two other methods through the context so that it does not have to be done twice.

abstract can_handle(uri: str, context: Any) → bool

Tell whether the request can be handled by this request handler.

Returns True if the request can be handled and False if it cannot be handled and the next request handler should be tried.

Parameters:

uri – URI that has been requested by the client. The URI includes the full request path including the query string (if present) and has not been URL decoded.
context – context object that was returned by prepare_context.

Returns:

True if this request handler can handle the specified request, False if the request should be deferred to the next handler.

abstract handle(request_info: HttpRequestInfo, body: BufferedIOBase, context: Any) → Tuple[HTTPStatus, Mapping[str, str] | None, BufferedIOBase | None]

Handle the request.

This method returns a tuple of three items. The first item is the HTTP status code, the second item are the headers that shall be sent to the client, and the third is a file-like object from which the data for the requested file can be read. The returned file-like object must supply its data in binary form.

Parameters:

request_info – information about the request that shall be handled.
body – file-like object that provides the request body sent by the client. This file-like object returns bytes when reading.
context – context object that was returned by prepare_context.

Returns:

tuple of the HTTP status code, the response headers, and a file-like object that provides the data that is transferred to the client. The file-like object must provide binary data. The response headers may be None, which has the same effect as supplying an empty dict (no headers are added to the response). The file-like object may also be None, which means that the body of the response is empty. Typically, this is only useful when indicating an error (status code >= 400). In this case, a body with an appropriate error message for the status code is generated by the server.

prepare_context(uri: str) → Any

Prepare a context object for use by can_handle and handle. This method is called for each request before calling can_handle.

This is useful when both function need to do some processing on the URI. This processing can be implemented in prepare_context and passed to the two other methods through the context so that it does not have to be done twice.

The return value of this method is passed to can_handle and handle. The default implementation simply returns None.

Parameters:: uri – URI that has been requested by the client. The URI includes the full request path including the query string (if present) and has not been URL decoded.
Returns:: context object that is passed to can_handle and handle.

class vinegar.http.server.HttpRequestInfo(*, client_address: Tuple[str, int] | Tuple[str, int, int, int], headers: HTTPMessage, method: str, server_address: Tuple[str, int] | Tuple[str, int, int, int], uri: str)

Request information passed to the HttpRequestHandler.

client_address: Tuple[str, int] | Tuple[str, int, int, int]

Socket address of the client side of the connection.

This always is a tuple, but the number of items and type of the items inside the tuple depends on the address family in use. Typically, the first item is the hostname or IP address of the client and the second item is the port number.

headers: HTTPMessage: HTTP headers provided by the client.

method: str

Request method that was specified by the client.

This is a string like GET, POST, PUT, etc.

server_address: Tuple[str, int] | Tuple[str, int, int, int]

Socket address of the server side of the connection.

This always is a tuple, but the number of items and type of the items inside the tuple depends on the address family in use. Typically, the first item is the hostname or IP address of the server and the second item is the port number.

uri: str

Full, undecoded request URI.

This includes both the path and the query string (if specified).

Example: /path/to/resource?abc=456

class vinegar.http.server.HttpServer(request_handlers: List[HttpRequestHandler], bind_address: str = '::', bind_port: int = 80)

HTTP server. This server can serve arbitrary resources, not just files on the file system. At the moment, it only supports the DELETE, GET, HEAD, POST, and PUT request methods.

This server is internally implemented using the http.server.HTTPServer class.

The server internally uses a daemon thread that processes incoming requests. For each request, it creates a new thread that processes this request and sends the requested data to the client.

start()

Start this server instance.

If the server is already running, this method does nothing.

stop()

Stop this server instance.

If the server is not running, this method does nothing.

vinegar.http.server.create_http_server(request_handlers: List[HttpRequestHandler], bind_address: str = '::', bind_port: int = 80)

Create a new HTTP server. The server is not started and its socket is not opened or bound when constructing the server object. Instead, start must be called to start the server.

Parameters:

request_handlers – List of request handlers than can handle read requests for this server. The request handlers are tried in order. The first request handler that can handle a request is used. If no request handler that can handle the request is found, an error is signaled to the client.
bind_address – Address of the interface on which the HTTP server shall listen for incoming connections. By default, the server listens on all local interfaces.
bind_port – Number of the TCP port on which the HTTP server shall listen for incoming connections. By default, the server listens on TCP port 80, this is the officially registered port for HTTP.