# Python API Reference

nghttp2 offers some high level Python API to C library. The bindings currently provide HPACK compressor and decompressor classes and HTTP/2 server class.

The extension module is called `nghttp2`.

`make` will build the bindings. The target Python version is determined by configure script. If the detected Python version is not what you expect, specify a path to Python executable in `PYTHON` variable as an argument to configure script (e.g., `./configure PYTHON=/usr/bin/python3.8`).

## 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

Note

We use `asyncio` for HTTP/2 server classes, and ALPN. Therefore, Python 3.8 or later is required to use these objects. To explicitly configure nghttp2 build to use Python 3.8, specify the `PYTHON` variable to the path to Python 3.8 executable when invoking configure script like this:

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

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.

  headers

    Request header fields.

  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`, `io.IOBase` or callable, called body generator, which takes one parameter, size. The body generator generates response body. It can pause generation of response so that it can wait for slow backend data generation. When invoked, it should return tuple, byte string at most size length and flag. The flag is either `DATA_OK`, `DATA_EOF` or `DATA_DEFERRED`. For non-empty byte string and it is not the last chunk of response, `DATA_OK` must be returned as flag. If this is the last chunk of the response (byte string could be `None`), `DATA_EOF` must be returned as flag. If there is no data available right now, but additional data are anticipated, return tuple (`None`, `DATA_DEFERRED`). When data arrived, call `resume()` and restart response body transmission.

    Only the body generator can pause response body generation; instance of `io.IOBase` must not block.

    If instance of `str` is specified as body, 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 has the same semantics of body parameter of `send_response()`.

    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.

  resume()

    Signals the restarting of response body transmission paused by `DATA_DEFERRED` from the body generator (see `send_response()` about the body generator). It is not an error calling this method while response body transmission is not paused.

nghttp2.DATA_OK

  `DATA_OK` indicates non empty data is generated from body generator.

nghttp2.DATA_EOF

  `DATA_EOF` indicates the end of response body.

nghttp2.DATA_DEFERRED

  `DATA_DEFERRED` indicates that data are not available right now and response should be paused.

The following example illustrates `HTTP2Server` and `BaseRequestHandler` usage:

    #!/usr/bin/env python3

    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 | ssl.OP_NO_SSLv3
    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()

The following example illustrates HTTP/2 server using asynchronous response body generation. This is simplified reverse proxy:

    #!/usr/bin/env python3

    import ssl
    import os
    import urllib
    import asyncio
    import io

    import nghttp2

    @asyncio.coroutine
    def get_http_header(handler, url):
        url = urllib.parse.urlsplit(url)
        ssl = url.scheme == 'https'
        if url.port == None:
            if url.scheme == 'https':
                port = 443
            else:
                port = 80
        else:
            port = url.port

        connect = asyncio.open_connection(url.hostname, port, ssl=ssl)
        reader, writer = yield from connect
        req = 'GET {path} HTTP/1.0\r\n\r\n'.format(path=url.path or '/')
        writer.write(req.encode('utf-8'))
        # skip response header fields
        while True:
            line = yield from reader.readline()
            line = line.rstrip()
            if not line:
                break
        # read body
        while True:
            b = yield from reader.read(4096)
            if not b:
                break
            handler.buf.write(b)
        writer.close()
        handler.buf.seek(0)
        handler.eof = True
        handler.resume()

    class Body:
        def __init__(self, handler):
            self.handler = handler
            self.handler.eof = False
            self.handler.buf = io.BytesIO()

        def generate(self, n):
            buf = self.handler.buf
            data = buf.read1(n)
            if not data and not self.handler.eof:
                return None, nghttp2.DATA_DEFERRED
            return data, nghttp2.DATA_EOF if self.handler.eof else nghttp2.DATA_OK

    class Handler(nghttp2.BaseRequestHandler):

        def on_headers(self):
            body = Body(self)
            asyncio.async(get_http_header(
                self, 'http://localhost' + self.path.decode('utf-8')))
            self.send_response(status=200, body=body.generate)

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

    server = nghttp2.HTTP2Server(('127.0.0.1', 8443), Handler, ssl=ctx)
    server.serve_forever()