blinkenxmas.http

The blinkenxmas.http module defines classes for parsing HTTP requests and constructing a response. This is a very basic implementation intended for use with the standard library’s http.server.

HTTPResponse, in particular, accepts a wide variety of inputs including file-like objects, pathlib.Path instances, strings, or byte-strings and will attempt to handle determination of encodings, content types automatically. Furthermore, given the originating request, it will handle cache and range-request response headers implicitly.

Several other functions are also provided for parsing HTTP Content- headers, and MIME multipart form-data.

Classes

class blinkenxmas.http.DummyResponse(request, **kwargs)[source]

An HTTP response that does nothing; useful for things that need to keep a client connection for whatever reason.

class blinkenxmas.http.HTTPResponse(request, body=None, *, status_code=HTTPStatus.OK, content_length=None, accept_ranges=True, filename=None, mime_type=None, encoding=None, last_modified=None, etag=None, headers=None)[source]

An HTTP response.

The request is the http.server.BaseHTTPRequestHandler instance representing the original request. The body (which forms the body of the response) may contain a str, bytes, or a file-like object.

Other parameters represent typical HTTP headers and, if not given, will be derived from the body where possible.

Parameters:

  • request (http.server.BaseHTTPRequestHandler) – The request instance representing the client’s request.

  • body –

    The object containing the body of the response. Ultimately this will be converted to a file-like object (IOBase descendent) in the stream attribute. This can be:

    • A file-like object in which case it will be used directly as the value of stream.

    • A str. This will be converted to a io.BytesIO stream with UTF-8 encoding.

    • A bytes string. This will be used verbatim as the content of a io.BytesIO stream.

    • A pathlib.Path. This will be opened as a binary file.

  • status_code (http.HTTPStatus) – The HTTP status code of the response. Expected to be a http.HTTPStatus attribute. Defaults to http.HTTPStatus.OK.

  • content_length (int) – The number of bytes in the response body. If not specified, and the body stream is seekable, this will be filled out automatically.

  • accept_ranges (bool) –

    If True (the default), handle “bytes” ranges automatically.

    Specifically, if this is set, the response will automatically handle sending only those ranges requested. It will re-write the “Content-Length”, “Content-Type”, “Content-Range”, and “Accept-Ranges” headers accordingly as necessary.

  • filename (str) – The original filename of the body (if any). If not specified, will be filled out automatically from the name property of the stream if it exists.

  • mime_type (str) – The MIME type of the response body. If not specified, will be determined automatically from the filename (if that was specified or determined).

  • encoding (str) – The encoding of the response body. If not specified, will be determined automatically from the filename (if that was specified or determined).

  • last_modified (datetime.datetime) – The last modification date of the response body. If this is specified it must be a time-zone aware datetime instance. If not specified, will be determined automatically (if possible) from the last modification date of the file containing the body content.

  • headers (dict) – Additional headers to include in the response.

check_cached()[source]

Check if the response is fresh in the client’s cache.

If the request is GET or HEAD with appropriate caching tests (If-Modified-Since and/or If-None-Match), and the response has appropriate caching responses then this method will (if the response is still “fresh” in the client’s cache), modify the status_code to http.HTTPStatus.NOT_MODIFIED and set stream to None.

check_ranges()[source]

Check if the request wanted a partial response (if the “Range:” header was included).

If the accept_ranges parameter was True at construction (the default), and a range or ranges were requested, this handles re-writing the response accordingly (this may include re-writing the status code, “Content-Length”, “Content-Type”, “Content-Range”, and “Accept-Ranges” headers).

send_body()[source]

Transmit the response body to the client.

send_headers()[source]

Transmit the response’s headers to the client.

class blinkenxmas.http.HTTPHeaders(iterable=None, **kwargs)[source]

Represents the headers of an HTTP request as a mutable mapping, handling correction of headers to “canonical” capitalization.

Functions

blinkenxmas.http.parse_content_value(s)[source]

Parse the content of an HTTP Content-* header’s value, s. The result is a tuple of (value, attrs) where value is the principal value (the part before the first semi-colon, if any), and attrs is a dictionary of attributes that follow the principal value.

blinkenxmas.http.split_multipart(request)[source]

Given request, a HTTPRequestHandler, which must have a Content-Type of multipart/, yield each part of the multipart body as a separate (headers, content) tuple. The *headers are returned as a HTTPHeaders instance, and the content as a file-like object.

blinkenxmas.http.parse_formdata(request)[source]

Given request, a HTTPRequestHandler, which must have a Content-Type of “multipart/form-data”, split the multipart body into its constituent parts, and return a dict mapping form names to their corresponding content.

Short text or binary values are returned as str or bytes values respectively. Anything with a “filename” attribute, or which exceeds a relatively large string size (currently 64KB) will be returned as a file-like object.