Python API

HTTPolice can be used as a Python library: for example, to analyze requests or responses as part of a test suite. It is not intended to be used inside live production processes.

Example

import io
import httpolice

exchanges = [
    httpolice.Exchange(
        httpolice.Request(u'https',
                          u'GET', u'/index.html', u'HTTP/1.1',
                          [(u'Host', b'example.com')],
                          b''),
        [
            httpolice.Response(u'HTTP/1.1', 401, u'Unauthorized',
                               [(u'Content-Type', b'text/plain')],
                               b'No way!'),
        ]
    )
]

bad_exchanges = []

for exch in exchanges:
    exch.silence([1089, 1227])      # Errors we don't care about
    httpolice.check_exchange(exch)
    if any(notice.severity > httpolice.Severity.comment
           for resp in exch.responses       # We only care about responses
           for notice in resp.notices):
        bad_exchanges.append(exch)

if bad_exchanges:
    with io.open('report.html', 'wb') as f:
        httpolice.html_report(bad_exchanges, f)
    print('%d exchanges had problems; report written to file' %
          len(bad_exchanges))

API reference

class httpolice.Request(scheme, method, target, version, header_entries, body, trailer_entries=None, remark=None)
Parameters:
  • scheme – The scheme of the request URI, as a Unicode string (usually u'http' or u'https'), or None if unknown (this disables some checks).
  • method – The request method, as a Unicode string.
  • target

    The request target, as a Unicode string. It must be in one of the four forms defined by RFC 7230. (For HTTP/2, it can be reconstructed from pseudo-headers.)

  • version

    The request’s protocol version, as a Unicode string, or None if unknown (this disables some checks).

    For requests sent over HTTP/1.x connections, this should be the HTTP version sent in the request line, such as u'HTTP/1.0' or u'HTTP/1.1'.

    For requests sent over HTTP/2 connections, this should be u'HTTP/2'.

  • header_entries

    A list of the request’s headers (may be empty). It must not include HTTP/2 pseudo-headers.

    Every item of the list must be a (name, value) pair.

    name must be a Unicode string.

    value may be a byte string or a Unicode string. If it is Unicode, HTTPolice will assume that it has been decoded from ISO-8859-1 (the historic encoding of HTTP), and will encode it back into ISO-8859-1 before any processing.

  • body

    The request’s payload body, as a byte string, or None if unknown (this disables some checks).

    If the request has no payload (like a GET request), this should be the empty string b''.

    This must be the payload body as defined by RFC 7230: after removing any Transfer-Encoding (like chunked), but before removing any Content-Encoding (like gzip).

  • trailer_entries

    A list of headers from the request’s trailer part (as found in chunked coding or HTTP/2), or None if there is no trailer part.

    The format is the same as for header_entries.

  • remark – If not None, this Unicode string will be shown above the request in HTML reports (when the appropriate option is enabled). For example, it can be used to identify the source of the data: u'from somefile.dat, offset 1337'.
notices

A list of Complaint instances reported on this object.

silence(notice_ids)

Silence unwanted notices on this object.

Parameters:notice_ids – An iterable of notice IDs that will be silenced on this object, so they don’t appear in notices or in reports.

class httpolice.Response(version, status, reason, header_entries, body, trailer_entries=None, remark=None)
Parameters:
  • version

    The response’s protocol version, as a Unicode string, or None if unknown (this disables some checks).

    For responses sent over HTTP/1.x connections, this should be the HTTP version sent in the status line, such as u'HTTP/1.0' or u'HTTP/1.1'.

    For responses sent over HTTP/2 connections, this should be u'HTTP/2'.

  • status – The response’s status code, as an integer.
  • reason – The response’s reason phrase (such as “OK” or “Not Found”), as a Unicode string, or None if unknown (as in HTTP/2).
  • header_entries

    A list of the response’s headers (may be empty). It must not include HTTP/2 pseudo-headers.

    Every item of the list must be a (name, value) pair.

    name must be a Unicode string.

    value may be a byte string or a Unicode string. If it is Unicode, HTTPolice will assume that it has been decoded from ISO-8859-1 (the historic encoding of HTTP), and will encode it back into ISO-8859-1 before any processing.

  • body

    The response’s payload body, as a byte string, or None if unknown (this disables some checks).

    If the response has no payload (like 204 or 304 responses), this should be the empty string b''.

    This must be the payload body as defined by RFC 7230: after removing any Transfer-Encoding (like chunked), but before removing any Content-Encoding (like gzip).

  • trailer_entries

    A list of headers from the response’s trailer part (as found in chunked coding or HTTP/2), or None if there is no trailer part.

    The format is the same as for header_entries.

  • remark – If not None, this Unicode string will be shown above this response in HTML reports (when the appropriate option is enabled). For example, it can be used to identify the source of the data: u'from somefile.dat, offset 1337'.
notices

A list of Complaint instances reported on this object.

silence(notice_ids)

Silence unwanted notices on this object.

Parameters:notice_ids – An iterable of notice IDs that will be silenced on this object, so they don’t appear in notices or in reports.

class httpolice.Exchange(req, resps)
Parameters:
  • req – The request, as a Request object. If it is not available, you can pass None, and the responses will be checked on their own. However, this disables many checks which rely on context information from the request.
  • resps – The responses to req, as a list of Response objects. Usually this will be a list of 1 element. If you only want to check the request, pass an empty list [].
request

The Request object passed to the constructor.

responses

The list of Response objects passed to the constructor.

silence(notice_ids)

Silence unwanted notices on this object.

Parameters:notice_ids – An iterable of notice IDs that will be silenced on this object, so they don’t appear in notices or in reports.

httpolice.check_exchange(exch)

Run all checks on the exchange exch, modifying it in place.


class httpolice.Complaint

A notice as reported in a particular place.

Create new instance of Complaint(notice, context)

id

The notice’s ID (an integer).

severity

The notice’s severity, as a member of the Severity enumeration.


class httpolice.Severity

A notice’s severity.

This is a Python 3.4 style enumeration with the additional feature that its members are ordered:

>>> Severity.comment < Severity.error
True

The underlying values of this enumeration are not part of the API.

comment = 1
debug = 0
error = 2

httpolice.text_report(exchanges, buf)

Generate a plain-text report with check results.

Parameters:
  • exchanges – An iterable of Exchange objects. They must be already processed by check_exchange().
  • buf – The file (or file-like object) to which the report will be written. It must be opened in binary mode (not text).

httpolice.html_report(exchanges, buf)

Generate an HTML report with check results.

Parameters:
  • exchanges – An iterable of Exchange objects. They must be already processed by check_exchange().
  • buf – The file (or file-like object) to which the report will be written. It must be opened in binary mode (not text).

Integration helpers

Functions that may be useful for integrating with HTTPolice.

httpolice.helpers.headers_from_cgi(cgi_dict)

Convert CGI variables into header entries.

Parameters:cgi_dict – A mapping of CGI-like meta-variables, as found in (for example) WSGI’s environ or django.http.HttpRequest.META.
Returns:A list of header entries, suitable for passing into httpolice.Request.
httpolice.helpers.pop_pseudo_headers(entries)

Remove and return HTTP/2 pseudo-headers from a list of headers.

Parameters:entries – A list of header name-value pairs, as would be passed to httpolice.Request or httpolice.Response. It will be modified in-place by removing all names that start with a colon (:).
Returns:A dictionary of the removed pseudo-headers.