Python API Reference¶

HPACK API¶

class nghttp2.HDDeflater(hd_table_bufsize_max=DEFLATE_MAX_HEADER_TABLE_SIZE)¶

This class is used to perform header compression. The hd_table_bufsize_max limits the usage of header table in the given amount of bytes. The default value is DEFLATE_MAX_HEADER_TABLE_SIZE. This is necessary because the deflater and inflater share the same amount of header table and the inflater decides that number. The deflater may not want to use all header table size because of limited memory availability. In that case, hd_table_bufsize_max can be used to cap the upper limit of table size whatever the header table size is chosen by the inflater.

deflate(headers)¶

Deflates the headers. The headers must be sequence of tuple of name/value pair, which are byte strings (not unicode string).

This method returns the deflated header block in byte string. Raises the exception if any error occurs.

set_no_refset(no_refset)¶

Tells the deflater not to use reference set if no_refset is evaluated to True. If that happens, on each subsequent invocation of deflate(), deflater will clear up refersent set.

change_table_size(hd_table_bufsize_max)¶

Changes header table size to hd_table_bufsize_max byte. if hd_table_bufsize_max is strictly larger than hd_table_bufsize_max given in constructor, hd_table_bufsize_max is used as header table size instead.

Raises the exception if any error occurs.

get_hd_table()¶

Returns copy of current dynamic header table.

The following example shows how to deflate header name/value pairs:

import binascii, nghttp2

deflater = nghttp2.HDDeflater()

res = deflater.deflate([(b'foo', b'bar'),
                        (b'baz', b'buz')])

print(binascii.b2a_hex(res))

class nghttp2.HDInflater¶

This class is used to perform header decompression.

inflate(data)¶

Inflates the deflated header block data. The data must be byte string.

Raises the exception if any error occurs.

change_table_size(hd_table_bufsize_max)¶

Changes header table size to hd_table_bufsize_max byte.

Raises the exception if any error occurs.

get_hd_table()¶

Returns copy of current dynamic header table.

The following example shows how to inflate deflated header block:

deflater = nghttp2.HDDeflater()

data = deflater.deflate([(b'foo', b'bar'),
                         (b'baz', b'buz')])

inflater = nghttp2.HDInflater()

hdrs = inflater.inflate(data)

print(hdrs)

nghttp2.print_hd_table(hdtable)¶

Convenient function to print hdtable to the standard output. The hdtable is the one retrieved by HDDeflater.get_hd_table() or HDInflater.get_hd_table(). This function does not work if header name/value cannot be decoded using UTF-8 encoding.

In output, s=N means the entry occupies N bytes in header table. If r=y, then the entry is in the reference set.

nghttp2.DEFAULT_HEADER_TABLE_SIZE¶

The default header table size, which is 4096 as per HTTP/2 specification.

nghttp2.DEFLATE_MAX_HEADER_TABLE_SIZE¶

The default header table size for deflater. The initial value is 4096.

HTTP/2 servers¶

$ ./configure PYTHON=/usr/bin/python3.4

class nghttp2.HTTP2Server(address, RequestHandlerClass, ssl=None)¶

This class builds on top of the asyncio event loop. On construction, RequestHandlerClass must be given, which must be a subclass of BaseRequestHandler class.

The address must be a tuple of hostname/IP address and port to bind. If hostname/IP address is None, all interfaces are assumed.

To enable SSL/TLS, specify instance of ssl.SSLContext in ssl. Before passing ssl to BaseEventLoop.create_server(), ALPN protocol identifiers are set using ssl.SSLContext.set_npn_protocols().

To disable SSL/TLS, omit ssl or specify None.

serve_forever()¶

Runs server and processes incoming requests forever.

class nghttp2.BaseRequestHandler(http2, stream_id)¶

The class is used to handle the single HTTP/2 stream. By default, it does not nothing. It must be subclassed to handle each event callback method.

The first callback method invoked is on_headers(). It is called when HEADERS frame, which includes request header fields, is arrived.

If request has request body, on_data() is invoked for each chunk of received data chunk.

When whole request is received, on_request_done() is invoked.

When stream is closed, on_close() is called.

The application can send response using send_response() method. It can be used in on_headers(), on_data() or on_request_done().

The application can push resource using push() method. It must be used before send_response() call.

A BaseRequestHandler has the following instance variables:

client_address¶

Contains a tuple of the form (host, port) referring to the client's address.

stream_id¶

Stream ID of this stream

scheme¶

Scheme of the request URI. This is a value of :scheme header field.

method¶

Method of this stream. This is a value of :method header field.

host¶

This is a value of :authority or host header field.

path¶

This is a value of :path header field.

A BaseRequestHandler has the following methods:

on_headers()¶

Called when request HEADERS is arrived. By default, this method does nothing.

on_data(data)¶

Called when a chunk of request body data is arrived. This method will be called multiple times until all data are received. By default, this method does nothing.

on_request_done()¶

Called when whole request was received. By default, this method does nothing.

on_close(error_code)¶

Called when stream is about to close. The error_code indicates the reason of closure. If it is 0, the stream is going to close without error.

send_response(status=200, headers=None, body=None)¶

Send response. The status is HTTP status code. The headers is additional response headers. The :status header field will be appended by the library. The body is the response body. It could be None if response body is empty. Or it must be instance of either str, bytes or io.IOBase. If instance of str is specified, it will be encoded using UTF-8.

The headers is a list of tuple of the form (name, value). The name and value can be either byte string or unicode string. In the latter case, they will be encoded using UTF-8.

Raises the exception if any error occurs.

push(path, method='GET', request_headers=None, status=200, headers=None, body=None)¶

Push a specified resource. The path is a path portion of request URI for this resource. The method is a method to access this resource. The request_headers is additional request headers to access this resource. The :scheme, :method, :authority and :path are appended by the library. The :scheme and :authority are inherited from request header fields of the associated stream.

The status is HTTP status code. The headers is additional response headers. The :status header field is appended by the library. The body is the response body. It could be None if response body is empty. Or it must be instance of either str, bytes or io.IOBase. If instance of str is specified, it is encoded using UTF-8.

The headers and request_headers are a list of tuple of the form (name, value). The name and value can be either byte string or unicode string. In the latter case, they will be encoded using UTF-8.

Returns an instance of RequestHandlerClass specified in HTTP2Server constructor for the pushed resource.

Raises the exception if any error occurs.

The following example illustrates HTTP2Server and BaseRequestHandler usage:

#!/usr/bin/env python

import io, ssl
import nghttp2

class Handler(nghttp2.BaseRequestHandler):

    def on_headers(self):
        self.push(path='/css/style.css',
                  request_headers = [('content-type', 'text/css')],
                  status=200,
                  body='body{margin:0;}')

        self.send_response(status=200,
                           headers = [('content-type', 'text/plain')],
                           body=io.BytesIO(b'nghttp2-python FTW'))

ctx = ssl.SSLContext(ssl.PROTOCOL_SSLv23)
ctx.options = ssl.OP_ALL | ssl.OP_NO_SSLv2
ctx.load_cert_chain('server.crt', 'server.key')

# give None to ssl to make the server non-SSL/TLS
server = nghttp2.HTTP2Server(('127.0.0.1', 8443), Handler, ssl=ctx)
server.serve_forever()