



  

hpack 4.0.0 documentation

 [hpack](index.html#document-index) 

 stable

 

* [Installing hpack](index.html#document-installation)

	+ [Using nghttp2](index.html#using-nghttp2)

* [hpack API](index.html#document-api)

* [Vulnerability Notifications](index.html#document-security/index)

	+ [Known Vulnerabilities](index.html#known-vulnerabilities)

[hpack](index.html#document-index)

* [Docs](index.html#document-index) »

* hpack 4.0.0 documentation

* [Edit on GitHub](https://github.com/python-hyper/hpack/blob/9a2c26cb58211d30f7f02ed93dfb6b03830b141d/docs/source/index.rst)

---

hpack: HTTP/2 Header Compression for Python[¶](#hpack-http-2-header-compression-for-python "Permalink to this headline")

========================================================================================================================

hpack provides a simple Python interface to the [HPACK](https://tools.ietf.org/html/rfc7541) 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 [nghttp2](https://nghttp2.org/).

Using hpack is easy:

```

from hpack import Encoder, Decoder

e = Encoder()

encoded\_bytes = e.encode(headers)

d = Decoder()

decoded\_headers = d.decode(encoded\_bytes)

```

hpack will transparently use nghttp2 on CPython if it’s available, gaining even

better compression efficiency and speed, but it also makes available a

pure-Python implementation that conforms strictly to [RFC 7541](https://tools.ietf.org/html/rfc7541).

Contents[¶](#contents "Permalink to this headline")

---------------------------------------------------

### Installing hpack[¶](#installing-hpack "Permalink to this headline")

hpack is trivial to install from the Python Package Index. Simply run:

```

$ pip install hpack

```

Alternatively, feel free to download one of the release tarballs from

[our GitHub page](https://github.com/python-hyper/hpack), extract it to your favourite directory, and then run

```

$ python setup.py install

```

hpack has no external dependencies.

#### Using nghttp2[¶](#using-nghttp2 "Permalink to this headline")

If you want to use nghttp2 with hpack, all you need to do is install it along

with its Python bindings. Consult [nghttp2’s documentation](https://nghttp2.org/documentation/) for instructions

on how to install it.

### hpack API[¶](#hpack-api "Permalink to this headline")

This document provides the HPACK API.

*class* `hpack.``Encoder`[[source]](_modules/hpack/hpack.html#Encoder)[¶](#hpack.Encoder "Permalink to this definition")

An HPACK encoder object. This object takes HTTP headers and emits encoded

HTTP/2 header blocks.

`encode`(*headers*, *huffman=True*)[[source]](_modules/hpack/hpack.html#Encoder.encode)[¶](#hpack.Encoder.encode "Permalink to this definition")

Takes a set of headers and encodes them into a HPACK-encoded header

block.

| Parameters: | * **headers** – The headers to encode. Must be either an iterable of

tuples, an iterable of [`HeaderTuple`](#hpack.HeaderTuple "hpack.HeaderTuple"), or a `dict`.

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 `(name, value)`. If they

are three-tuples, they must be of the format

`(name, value, sensitive)`, where `sensitive` is a

boolean value indicating whether the header should be

added to header tables anywhere. If not present,

`sensitive` defaults to `False`.

If an iterable of [`HeaderTuple`](#hpack.HeaderTuple "hpack.HeaderTuple"), the tuples must always be

two-tuples. Instead of using `sensitive` as a third

tuple entry, use [`NeverIndexedHeaderTuple`](#hpack.NeverIndexedHeaderTuple "hpack.NeverIndexedHeaderTuple") to request that

the field never be indexed.

Warning

HTTP/2 requires that all special headers

(headers whose names begin with `:` characters)

appear at the *start* of the header block. While

this method will ensure that happens for `dict`

subclasses, callers using any other iterable of

tuples **must** ensure they place their special

headers at the start of the iterable.

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.

* **huffman** – (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.

 |

| Returns: | A bytestring containing the HPACK-encoded header block. |

`header_table_size`[¶](#hpack.Encoder.header_table_size "Permalink to this definition")

Controls the size of the HPACK header table.

*class* `hpack.``Decoder`(*max\_header\_list\_size=65536*)[[source]](_modules/hpack/hpack.html#Decoder)[¶](#hpack.Decoder "Permalink to this definition")

An HPACK decoder object.

Changed in version 2.3.0: Added `max\_header\_list\_size` argument.

| Parameters: | **max\_header\_list\_size** (`int`) – 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.

If this amount of data is exceeded, a OversizedHeaderListError

<hpack.OversizedHeaderListError> exception will be raised. At this

point the connection should be shut down, as the HPACK state will no

longer be usable.

Defaults to 64kB. |

`decode`(*data*, *raw=False*)[[source]](_modules/hpack/hpack.html#Decoder.decode)[¶](#hpack.Decoder.decode "Permalink to this definition")

Takes an HPACK-encoded header block and decodes it into a header set.

| Parameters: | * **data** – A bytestring representing a complete HPACK-encoded header

block.

* **raw** – (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

 |

| Returns: | A list of two-tuples of `(name, value)` representing the

HPACK-encoded headers, in the order they were decoded. |

| Raises: | [**HPACKDecodingError**](index.html#hpack.HPACKDecodingError "hpack.HPACKDecodingError") – If an error is encountered while decoding

the header block. |

`header_table_size`[¶](#hpack.Decoder.header_table_size "Permalink to this definition")

Controls the size of the HPACK header table.

*class* `hpack.``HeaderTuple`[[source]](_modules/hpack/struct.html#HeaderTuple)[¶](#hpack.HeaderTuple "Permalink to this definition")

A data structure that stores a single header field.

HTTP headers can be thought of as tuples of `(field name, field value)`.

A single header block is a sequence of such tuples.

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.

This class stores a header that can be added to the compression context. In

all other ways it behaves exactly like a tuple.

*class* `hpack.``NeverIndexedHeaderTuple`[[source]](_modules/hpack/struct.html#NeverIndexedHeaderTuple)[¶](#hpack.NeverIndexedHeaderTuple "Permalink to this definition")

A data structure that stores a single header field that cannot be added to

a HTTP/2 header compression context.

*class* `hpack.``HPACKError`[[source]](_modules/hpack/exceptions.html#HPACKError)[¶](#hpack.HPACKError "Permalink to this definition")

The base class for all `hpack` exceptions.

*class* `hpack.``HPACKDecodingError`[[source]](_modules/hpack/exceptions.html#HPACKDecodingError)[¶](#hpack.HPACKDecodingError "Permalink to this definition")

An error has been encountered while performing HPACK decoding.

*class* `hpack.``InvalidTableIndex`[[source]](_modules/hpack/exceptions.html#InvalidTableIndex)[¶](#hpack.InvalidTableIndex "Permalink to this definition")

An invalid table index was received.

*class* `hpack.``OversizedHeaderListError`[[source]](_modules/hpack/exceptions.html#OversizedHeaderListError)[¶](#hpack.OversizedHeaderListError "Permalink to this definition")

A header list that was larger than we allow has been received. This may be

a DoS attack.

New in version 2.3.0.

*class* `hpack.``InvalidTableSizeError`[[source]](_modules/hpack/exceptions.html#InvalidTableSizeError)[¶](#hpack.InvalidTableSizeError "Permalink to this definition")

An attempt was made to change the decoder table size to a value larger than

allowed, or the list was shrunk and the remote peer didn’t shrink their

table size.

New in version 3.0.0.

### Vulnerability Notifications[¶](#vulnerability-notifications "Permalink to this headline")

This section of the page contains all known vulnerabilities in the HPACK

library. These vulnerabilities have all been reported to us via our

[vulnerability disclosure policy](http://python-hyper.org/en/latest/security.html#vulnerability-disclosure).

#### Known Vulnerabilities[¶](#known-vulnerabilities "Permalink to this headline")

| # | Vulnerability | Date Announced | First Version | Last Version | CVE |

| --- | --- | --- | --- | --- | --- |

| 1 | [HPACK Bomb](index.html#document-security/CVE-2016-6581) | 2016-08-04 | 1.0.0 | 2.2.0 | CVE-2016-6581 |

