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'
oru'https'
), orNone
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'
oru'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
(likechunked
), but before removing anyContent-Encoding
(likegzip
). - 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'
.
- scheme – The scheme of the request URI, as a Unicode string
(usually
-
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'
oru'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
(likechunked
), but before removing anyContent-Encoding
(likegzip
). - 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'
.
- version –
-
class
httpolice.
Exchange
(req, resps)¶ Parameters: - req – The request, as a
Request
object. If it is not available, you can passNone
, 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 ofResponse
objects. Usually this will be a list of 1 element. If you only want to check the request, pass an empty list[]
.
-
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.
- req – The request, as a
-
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.
-
id
¶ The notice’s ID (an integer).
-
-
class
httpolice.
Severity
¶ A notice’s severity.
This is a standard Python 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 bycheck_exchange()
. - buf – The file (or file-like object) to which the report will be written. It must be opened in binary mode (not text).
- exchanges – An iterable of
-
httpolice.
html_report
(exchanges, buf)¶ Generate an HTML report with check results.
Parameters: - exchanges – An iterable of
Exchange
objects. They must be already processed bycheck_exchange()
. - buf – The file (or file-like object) to which the report will be written. It must be opened in binary mode (not text).
- exchanges – An iterable of
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
ordjango.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
orhttpolice.Response
. It will be modified in-place by removing all names that start with a colon (:).Returns: A dictionary of the removed pseudo-headers.