nghttp2/doc/sources/python-apiref.rst

440 lines
14 KiB
ReStructuredText
Raw Normal View History

2014-05-13 14:46:39 +02:00
Python API Reference
====================
.. py:module:: nghttp2
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.5``).
2014-05-13 14:46:39 +02:00
HPACK API
---------
.. py:class:: 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
:py:data:`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.
.. py:method:: 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.
.. py:method:: 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 :py:meth:`deflate()`, deflater will clear up
refersent set.
.. py:method:: 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.
.. py:method:: get_hd_table()
Returns copy of current dynamic header table.
The following example shows how to deflate header name/value pairs:
.. code-block:: python
import binascii, nghttp2
deflater = nghttp2.HDDeflater()
res = deflater.deflate([(b'foo', b'bar'),
(b'baz', b'buz')])
print(binascii.b2a_hex(res))
.. py:class:: HDInflater()
This class is used to perform header decompression.
.. py:method:: inflate(data)
Inflates the deflated header block *data*. The *data* must be
byte string.
Raises the exception if any error occurs.
.. py:method:: change_table_size(hd_table_bufsize_max)
Changes header table size to *hd_table_bufsize_max* byte.
Raises the exception if any error occurs.
.. py:method:: get_hd_table()
Returns copy of current dynamic header table.
The following example shows how to inflate deflated header block:
.. code-block:: python
deflater = nghttp2.HDDeflater()
data = deflater.deflate([(b'foo', b'bar'),
(b'baz', b'buz')])
inflater = nghttp2.HDInflater()
hdrs = inflater.inflate(data)
print(hdrs)
.. py:function:: print_hd_table(hdtable)
Convenient function to print *hdtable* to the standard output. The
*hdtable* is the one retrieved by
:py:meth:`HDDeflater.get_hd_table()` or
:py:meth:`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.
.. py:data:: DEFAULT_HEADER_TABLE_SIZE
The default header table size, which is 4096 as per HTTP/2
specification.
.. py:data:: DEFLATE_MAX_HEADER_TABLE_SIZE
The default header table size for deflater. The initial value
is 4096.
HTTP/2 servers
--------------
.. note::
We use :py:mod:`asyncio` for HTTP/2 server classes, and ALPN.
Therefore, Python 3.5 or later is required to use these objects.
To explicitly configure nghttp2 build to use Python 3.5, specify
the ``PYTHON`` variable to the path to Python 3.5 executable when
2016-07-16 12:07:31 +02:00
invoking configure script like this:
.. code-block:: text
2014-05-13 14:46:39 +02:00
$ ./configure PYTHON=/usr/bin/python3.5
2014-05-13 14:46:39 +02:00
.. py:class:: HTTP2Server(address, RequestHandlerClass, ssl=None)
This class builds on top of the :py:mod:`asyncio` event loop. On
construction, *RequestHandlerClass* must be given, which must be a
subclass of :py:class:`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 :py:class:`ssl.SSLContext`
in *ssl*. Before passing *ssl* to
:py:func:`BaseEventLoop.create_server`, ALPN protocol identifiers
are set using :py:meth:`ssl.SSLContext.set_npn_protocols`.
To disable SSL/TLS, omit *ssl* or specify ``None``.
.. py:method:: serve_forever()
Runs server and processes incoming requests forever.
.. py:class:: 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 :py:meth:`on_headers()`. It is
called when HEADERS frame, which includes request header fields, is
arrived.
If request has request body, :py:meth:`on_data()` is invoked for
each chunk of received data chunk.
When whole request is received, :py:meth:`on_request_done()` is
invoked.
When stream is closed, :py:meth:`on_close()` is called.
The application can send response using :py:meth:`send_response()`
method. It can be used in :py:meth:`on_headers()`,
:py:meth:`on_data()` or :py:meth:`on_request_done()`.
The application can push resource using :py:meth:`push()` method.
It must be used before :py:meth:`send_response()` call.
A :py:class:`BaseRequestHandler` has the following instance
variables:
.. py:attribute:: client_address
Contains a tuple of the form ``(host, port)`` referring to the
client's address.
.. py:attribute:: stream_id
Stream ID of this stream
.. py:attribute:: scheme
Scheme of the request URI. This is a value of ``:scheme``
header field.
.. py:attribute:: method
Method of this stream. This is a value of ``:method`` header
field.
.. py:attribute:: host
This is a value of ``:authority`` or ``host`` header field.
.. py:attribute:: path
This is a value of ``:path`` header field.
.. py:attribute:: headers
Request header fields.
2014-05-13 14:46:39 +02:00
A :py:class:`BaseRequestHandler` has the following methods:
.. py:method:: on_headers()
Called when request HEADERS is arrived. By default, this method
does nothing.
.. py:method:: 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.
.. py:method:: on_request_done()
Called when whole request was received. By default, this method
does nothing.
.. py:method:: 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.
.. py:method:: 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``, :py:class:`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
2015-04-01 16:10:01 +02:00
at most size length and flag. The flag is either
:py:data:`DATA_OK`, :py:data:`DATA_EOF` or
:py:data:`DATA_DEFERRED`. For non-empty byte string and it is
not the last chunk of response, :py:data:`DATA_OK` must be
returned as flag. If this is the last chunk of the response
2015-04-01 16:10:01 +02:00
(byte string could be ``None``), :py:data:`DATA_EOF` must be
returned as flag. If there is no data available right now, but
additional data are anticipated, return tuple (``None``,
2015-05-12 03:49:42 +02:00
:py:data:`DATA_DEFERRED`). When data arrived, call
2015-04-01 16:10:01 +02:00
:py:meth:`resume()` and restart response body transmission.
Only the body generator can pause response body generation;
instance of :py:class:`io.IOBase` must not block.
If instance of ``str`` is specified as *body*, it will be
encoded using UTF-8.
2014-05-13 14:46:39 +02:00
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.
.. py:method:: 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 :py:meth:`send_response()`.
2014-05-13 14:46:39 +02:00
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
:py:class:`HTTP2Server` constructor for the pushed resource.
Raises the exception if any error occurs.
.. py:method:: resume()
Signals the restarting of response body transmission paused by
``DATA_DEFERRED`` from the body generator (see
:py:meth:`send_response()` about the body generator). It is not
an error calling this method while response body transmission is
not paused.
2015-04-01 16:10:01 +02:00
.. py:data:: DATA_OK
``DATA_OK`` indicates non empty data is generated from body generator.
.. py:data:: DATA_EOF
``DATA_EOF`` indicates the end of response body.
.. py:data:: DATA_DEFERRED
``DATA_DEFERRED`` indicates that data are not available right now
and response should be paused.
2014-05-13 14:46:39 +02:00
The following example illustrates :py:class:`HTTP2Server` and
:py:class:`BaseRequestHandler` usage:
.. code-block:: python
#!/usr/bin/env python
import io, ssl
2014-05-13 14:46:39 +02:00
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
2014-05-13 14:46:39 +02:00
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:
.. code-block:: python
#!/usr/bin/env python
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()