Python Module Index
+ ++ n | ||
+ | + nghttp2 | + |
From f6f6dadff43622e81ce7c1833a3b8cfd5312acf5 Mon Sep 17 00:00:00 2001
From: Tatsuhiro Tsujikawa
HPACK deflater object.
+Initializes *deflater_ptr for deflating name/values pairs.
+The deflate_hd_table_bufsize_max is the upper bound of header +table size the deflater will use.
+This function returns 0 if it succeeds, or one of the following +negative error codes:
+Deallocates any resources allocated for deflater.
+Sets the availability of reference set in the deflater. If +no_refset is nonzero, the deflater will first emit “Reference Set +Emptying” in the each subsequent invocation of +nghttp2_hd_deflate_hd() to clear up reference set. By default, +the deflater uses reference set.
+Changes header table size of the deflater to +settings_hd_table_bufsize_max bytes. This may trigger eviction +in the dynamic table.
+The settings_hd_table_bufsize_max should be the value received in +SETTINGS_HEADER_TABLE_SIZE.
+The deflater never uses more memory than +deflate_hd_table_bufsize_max bytes specified in +nghttp2_hd_deflate_new(). Therefore, if +settings_hd_table_bufsize_max > deflate_hd_table_bufsize_max, +resulting maximum table size becomes +deflate_hd_table_bufsize_max.
+This function returns 0 if it succeeds, or one of the following +negative error codes:
+Deflates the nva, which has the nvlen name/value pairs, into +the buf of length buflen.
+If buf is not large enough to store the deflated header block, +this function fails with NGHTTP2_ERR_INSUFF_BUFSIZE. The +caller should use nghttp2_hd_deflate_bound() to know the upper +bound of buffer size required to deflate given header name/value +pairs.
+Once this function fails, subsequent call of this function always +returns NGHTTP2_ERR_HEADER_COMP.
+After this function returns, it is safe to delete the nva.
+This function returns 0 if it succeeds, or one of the following +negative error codes:
+Returns an upper bound on the compressed size after deflation of +nva of length nvlen.
+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.4).
+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.
+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.
+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.
+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.
+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))
+
This class is used to perform header decompression.
+Inflates the deflated header block data. The data must be +byte string.
+Raises the exception if any error occurs.
+Changes header table size to hd_table_bufsize_max byte.
+Raises the exception if any error occurs.
+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)
+
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.
+The default header table size, which is 4096 as per HTTP/2 +specification.
+The default header table size for deflater. The initial value +is 4096.
+Note
+We use asyncio for HTTP/2 server classes. Therefore, +Python 3.4 or later is required to use these objects. To +explicitly configure nghttp2 build to use Python 3.4, specify the +PYTHON variable to the path to Python 3.4 executable when +invoking configure script like this:
+$ ./configure PYTHON=/usr/bin/python3.4
+
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.
+Runs server and processes incoming requests forever.
+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:
+Contains a tuple of the form (host, port) referring to the +client’s address.
+Stream ID of this stream
+Scheme of the request URI. This is a value of :scheme +header field.
+Method of this stream. This is a value of :method header +field.
+This is a value of :authority or host header field.
+This is a value of :path header field.
+A BaseRequestHandler has the following methods:
+Called when request HEADERS is arrived. By default, this method +does nothing.
+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.
+Called when whole request was received. By default, this method +does nothing.
+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. 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 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()
+