python/hpack: Updated for version 2.3.0.

Signed-off-by: Willy Sudiarto Raharjo <willysr@slackbuilds.org>

1 files changed, 313 insertions, 0 deletions

diff --git a/python/hpack/man_page/hpack.1 b/python/hpack/man_page/hpack.1
new file mode 100644
index 0000000000..f53f6d03f3
--- /dev/null
+++ b/python/hpack/man_page/hpack.1
@@ -0,0 +1,313 @@
+.\" Man page generated from reStructuredText.
+.
+.TH "HPACK" "1" "December 17, 2016" "2.3.0" "hpack"
+.SH NAME
+hpack \- hpack Documentation
+.
+.nr rst2man-indent-level 0
+.
+.de1 rstReportMargin
+\\$1 \\n[an-margin]
+level \\n[rst2man-indent-level]
+level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
+-
+\\n[rst2man-indent0]
+\\n[rst2man-indent1]
+\\n[rst2man-indent2]
+..
+.de1 INDENT
+.\" .rstReportMargin pre:
+. RS \\$1
+. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
+. nr rst2man-indent-level +1
+.\" .rstReportMargin post:
+..
+.de UNINDENT
+. RE
+.\" indent \\n[an-margin]
+.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.nr rst2man-indent-level -1
+.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
+..
+.sp
+hpack provides a simple Python interface to the \fI\%HPACK\fP compression algorithm,
+used to compress HTTP headers in HTTP/2. Used by some of the most popular
+HTTP/2 implementations in Python, HPACK offers a great Python interface as well
+as optional upgrade to optimised C\-based compression routines from \fI\%nghttp2\fP\&.
+.sp
+Using hpack is easy:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+from hpack import Encoder, Decoder
+
+e = Encoder()
+encoded_bytes = e.encode(headers)
+
+d = Decoder()
+decoded_headers = d.decode(encoded_bytes)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+hpack will transparently use nghttp2 on CPython if it\(aqs available, gaining even
+better compression efficiency and speed, but it also makes available a
+pure\-Python implementation that conforms strictly to \fI\%RFC 7541\fP\&.
+.SH CONTENTS
+.SS Installing hpack
+.sp
+hpack is trivial to install from the Python Package Index. Simply run:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+$ pip install hpack
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Alternatively, feel free to download one of the release tarballs from
+\fI\%our GitHub page\fP, extract it to your favourite directory, and then run
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+$ python setup.py install
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+hpack has no external dependencies.
+.SS Using nghttp2
+.sp
+If you want to use nghttp2 with hpack, all you need to do is install it along
+with its Python bindings. Consult \fI\%nghttp2\(aqs documentation\fP for instructions
+on how to install it.
+.SS hpack API
+.sp
+This document provides the HPACK API.
+.INDENT 0.0
+.TP
+.B class hpack.Encoder
+An HPACK encoder object. This object takes HTTP headers and emits encoded
+HTTP/2 header blocks.
+.INDENT 7.0
+.TP
+.B encode(headers, huffman=True)
+Takes a set of headers and encodes them into a HPACK\-encoded header
+block.
+.INDENT 7.0
+.TP
+.B Parameters
+.INDENT 7.0
+.IP \(bu 2
+\fBheaders\fP \-\- 
+.sp
+The headers to encode. Must be either an iterable of
+tuples, an iterable of \fBHeaderTuple\fP, or a \fBdict\fP\&.
+.sp
+If an iterable of tuples, the tuples may be either
+two\-tuples or three\-tuples. If they are two\-tuples, the
+tuples must be of the format \fB(name, value)\fP\&. If they
+are three\-tuples, they must be of the format
+\fB(name, value, sensitive)\fP, where \fBsensitive\fP is a
+boolean value indicating whether the header should be
+added to header tables anywhere. If not present,
+\fBsensitive\fP defaults to \fBFalse\fP\&.
+.sp
+If an iterable of \fBHeaderTuple\fP, the tuples must always be
+two\-tuples. Instead of using \fBsensitive\fP as a third
+tuple entry, use \fBNeverIndexedHeaderTuple\fP to request that
+the field never be indexed.
+.sp
+\fBWARNING:\fP
+.INDENT 2.0
+.INDENT 3.5
+HTTP/2 requires that all special headers
+(headers whose names begin with \fB:\fP characters)
+appear at the \fIstart\fP of the header block. While
+this method will ensure that happens for \fBdict\fP
+subclasses, callers using any other iterable of
+tuples \fBmust\fP ensure they place their special
+headers at the start of the iterable.
+.sp
+For efficiency reasons users should prefer to use
+iterables of two\-tuples: fixing the ordering of
+dictionary headers is an expensive operation that
+should be avoided if possible.
+.UNINDENT
+.UNINDENT
+
+.IP \(bu 2
+\fBhuffman\fP \-\- (optional) Whether to Huffman\-encode any header sent as
+a literal value. Except for use when debugging, it is
+recommended that this be left enabled.
+.UNINDENT
+.TP
+.B Returns
+A bytestring containing the HPACK\-encoded header block.
+.UNINDENT
+.UNINDENT
+.INDENT 7.0
+.TP
+.B header_table_size
+Controls the size of the HPACK header table.
+.UNINDENT
+.UNINDENT
+.INDENT 0.0
+.TP
+.B class hpack.Decoder(max_header_list_size=65536)
+An HPACK decoder object.
+.sp
+Changed in version 2.3.0: Added \fBmax_header_list_size\fP argument.
+
+.INDENT 7.0
+.TP
+.B Parameters
+\fBmax_header_list_size\fP (\fBint\fP) \-\- 
+.sp
+The maximum decompressed size we will allow
+for any single header block. This is a protection against DoS attacks
+that attempt to force the application to expand a relatively small
+amount of data into a really large header list, allowing enormous
+amounts of memory to be allocated.
+.sp
+If this amount of data is exceeded, a \fIOversizedHeaderListError
+<hpack.OversizedHeaderListError>\fP exception will be raised. At this
+point the connection should be shut down, as the HPACK state will no
+longer be useable.
+.sp
+Defaults to 64kB.
+
+.UNINDENT
+.INDENT 7.0
+.TP
+.B decode(data, raw=False)
+Takes an HPACK\-encoded header block and decodes it into a header set.
+.INDENT 7.0
+.TP
+.B Parameters
+.INDENT 7.0
+.IP \(bu 2
+\fBdata\fP \-\- A bytestring representing a complete HPACK\-encoded header
+block.
+.IP \(bu 2
+\fBraw\fP \-\- (optional) Whether to return the headers as tuples of raw
+byte strings or to decode them as UTF\-8 before returning
+them. The default value is False, which returns tuples of
+Unicode strings
+.UNINDENT
+.TP
+.B Returns
+A list of two\-tuples of \fB(name, value)\fP representing the
+HPACK\-encoded headers, in the order they were decoded.
+.TP
+.B Raises HPACKDecodingError
+If an error is encountered while decoding
+the header block.
+.UNINDENT
+.UNINDENT
+.INDENT 7.0
+.TP
+.B header_table_size
+Controls the size of the HPACK header table.
+.UNINDENT
+.UNINDENT
+.INDENT 0.0
+.TP
+.B class hpack.HeaderTuple
+A data structure that stores a single header field.
+.sp
+HTTP headers can be thought of as tuples of \fB(field name, field value)\fP\&.
+A single header block is a sequence of such tuples.
+.sp
+In HTTP/2, however, certain bits of additional information are required for
+compressing these headers: in particular, whether the header field can be
+safely added to the HPACK compression context.
+.sp
+This class stores a header that can be added to the compression context. In
+all other ways it behaves exactly like a tuple.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B class hpack.NeverIndexedHeaderTuple
+A data structure that stores a single header field that cannot be added to
+a HTTP/2 header compression context.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B class hpack.HPACKError
+The base class for all \fBhpack\fP exceptions.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B class hpack.HPACKDecodingError
+An error has been encountered while performing HPACK decoding.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B class hpack.InvalidTableIndex
+An invalid table index was received.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B class hpack.OversizedHeaderListError
+A header list that was larger than we allow has been received. This may be
+a DoS attack.
+.sp
+New in version 2.3.0.
+
+.UNINDENT
+.SS Vulnerability Notifications
+.sp
+This section of the page contains all known vulnerabilities in the HPACK
+library. These vulnerabilities have all been reported to us via our
+\fI\%vulnerability disclosure policy\fP\&.
+.SS Known Vulnerabilities
+.TS
+center;
+|l|l|l|l|l|l|.
+_
+T{
+#
+T}	T{
+Vulnerability
+T}	T{
+Date Announced
+T}	T{
+First Version
+T}	T{
+Last Version
+T}	T{
+CVE
+T}
+_
+T{
+1
+T}	T{
+\fBHPACK Bomb\fP
+T}	T{
+2016\-08\-04
+T}	T{
+1.0.0
+T}	T{
+2.2.0
+T}	T{
+CVE\-2016\-6581
+T}
+_
+.TE
+.SH AUTHOR
+Cory Benfield
+.SH COPYRIGHT
+2015, Cory Benfield
+.\" Generated by docutils manpage writer.
+.