hyperframe API¶

This document provides the hyperframe API.

All frame classes are subclasses of Frame, and provide the methods and attributes defined there. Additionally, some frames use the Priority and Padding mixins, and make the methods and attributes defined on those mixins available as well.

Rather than clutter up the documentation repeatedly documenting those methods and objects, we explicitly show the inheritance heirarchy of the frames: don’t forget to consule the parent classes before deciding if a method or attribute you need is not present!

class hyperframe.frame.Frame(stream_id, flags=())¶

The base class for all HTTP/2 frames.

body_len = None¶: The frame length, excluding the nine-byte header.

defined_flags = []¶: The flags defined on this type of frame.

flags = None¶: The flags set for this frame.

parse_body(data)¶

Given the body of a frame, parses it into frame data. This populates the non-header parts of the frame: that is, it does not populate the stream ID or flags.

Parameters:	data – A bytestring containing the body data of the frame. Must not contain more data than the length returned by `parse_frame_header`.

static parse_frame_header(header)¶

Takes a 9-byte frame header and returns a tuple of the appropriate Frame object and the length that needs to be read from the socket.

This populates the flags field, and determines how long the body is.

Raises:	hyperframe.exceptions.UnknownFrameError – If a frame of unknown type is received.

serialize()¶: Convert a frame into a bytestring, representing the serialized form of the frame.

stream_id = None¶: The stream identifier for the stream this frame was received on. Set to 0 for frames sent on the connection (stream-id 0).

type = None¶: The byte used to define the type of the frame.

class hyperframe.frame.Padding(stream_id, pad_length=0, **kwargs)¶

Mixin for frames that contain padding. Defines extra fields that can be used and set by frames that can be padded.

pad_length = None¶: The length of the padding to use.

class hyperframe.frame.Priority(stream_id, depends_on=None, stream_weight=None, exclusive=None, **kwargs)¶

Mixin for frames that contain priority data. Defines extra fields that can be used and set by frames that contain priority data.

depends_on = None¶: The stream ID of the stream on which this stream depends.

exclusive = None¶: Whether the exclusive bit was set.

stream_weight = None¶: The weight of the stream. This is an integer between 0 and 256.

class hyperframe.frame.DataFrame(stream_id, data=b'', **kwargs)¶

Bases: hyperframe.frame.Padding, hyperframe.frame.Frame

DATA frames convey arbitrary, variable-length sequences of octets associated with a stream. One or more DATA frames are used, for instance, to carry HTTP request or response payloads.

data = None¶: The data contained on this frame.

defined_flags = [Flag(name='END_STREAM', bit=1), Flag(name='PADDED', bit=8)]¶: The flags defined for DATA frames.

flow_controlled_length¶: The length of the frame that needs to be accounted for when considering flow control.

parse_body(data)¶

Given the body of a frame, parses it into frame data. This populates the non-header parts of the frame: that is, it does not populate the stream ID or flags.

Parameters:	data – A bytestring containing the body data of the frame. Must not contain more data than the length returned by `parse_frame_header`.

type = 0¶: The type byte for data frames.

class hyperframe.frame.PriorityFrame(stream_id, depends_on=None, stream_weight=None, exclusive=None, **kwargs)¶

Bases: hyperframe.frame.Priority, hyperframe.frame.Frame

The PRIORITY frame specifies the sender-advised priority of a stream. It can be sent at any time for an existing stream. This enables reprioritisation of existing streams.

defined_flags = []¶: The flags defined for PRIORITY frames.

parse_body(data)¶

Given the body of a frame, parses it into frame data. This populates the non-header parts of the frame: that is, it does not populate the stream ID or flags.

Parameters:	data – A bytestring containing the body data of the frame. Must not contain more data than the length returned by `parse_frame_header`.

type = 2¶: The type byte defined for PRIORITY frames.

class hyperframe.frame.RstStreamFrame(stream_id, error_code=0, **kwargs)¶

Bases: hyperframe.frame.Frame

The RST_STREAM frame allows for abnormal termination of a stream. When sent by the initiator of a stream, it indicates that they wish to cancel the stream or that an error condition has occurred. When sent by the receiver of a stream, it indicates that either the receiver is rejecting the stream, requesting that the stream be cancelled or that an error condition has occurred.

defined_flags = []¶: The flags defined for RST_STREAM frames.

error_code = None¶: The error code used when resetting the stream.

parse_body(data)¶

Given the body of a frame, parses it into frame data. This populates the non-header parts of the frame: that is, it does not populate the stream ID or flags.

Parameters:	data – A bytestring containing the body data of the frame. Must not contain more data than the length returned by `parse_frame_header`.

type = 3¶: The type byte defined for RST_STREAM frames.

class hyperframe.frame.SettingsFrame(stream_id=0, settings=None, **kwargs)¶

Bases: hyperframe.frame.Frame

The SETTINGS frame conveys configuration parameters that affect how endpoints communicate. The parameters are either constraints on peer behavior or preferences.

Settings are not negotiated. Settings describe characteristics of the sending peer, which are used by the receiving peer. Different values for the same setting can be advertised by each peer. For example, a client might set a high initial flow control window, whereas a server might set a lower value to conserve resources.

ENABLE_PUSH = 2¶: The byte that signals the SETTINGS_ENABLE_PUSH setting.

HEADER_TABLE_SIZE = 1¶: The byte that signals the SETTINGS_HEADER_TABLE_SIZE setting.

INITIAL_WINDOW_SIZE = 4¶: The byte that signals the SETTINGS_INITIAL_WINDOW_SIZE setting.

MAX_CONCURRENT_STREAMS = 3¶: The byte that signals the SETTINGS_MAX_CONCURRENT_STREAMS setting.

SETTINGS_MAX_FRAME_SIZE = 5¶: The byte that signals the SETTINGS_MAX_FRAME_SIZE setting.

SETTINGS_MAX_HEADER_LIST_SIZE = 6¶: The byte that signals the SETTINGS_MAX_HEADER_LIST_SIZE setting.

defined_flags = [Flag(name='ACK', bit=1)]¶: The flags defined for SETTINGS frames.

parse_body(data)¶

Given the body of a frame, parses it into frame data. This populates the non-header parts of the frame: that is, it does not populate the stream ID or flags.

Parameters:	data – A bytestring containing the body data of the frame. Must not contain more data than the length returned by `parse_frame_header`.

settings = None¶: A dictionary of the setting type byte to the value of the setting.

type = 4¶: The type byte defined for SETTINGS frames.

class hyperframe.frame.PushPromiseFrame(stream_id, promised_stream_id=0, data=b'', **kwargs)¶

Bases: hyperframe.frame.Padding, hyperframe.frame.Frame

The PUSH_PROMISE frame is used to notify the peer endpoint in advance of streams the sender intends to initiate.

data = None¶: The HPACK-encoded header block for the simulated request on the new stream.

defined_flags = [Flag(name='END_HEADERS', bit=4), Flag(name='PADDED', bit=8)]¶: The flags defined for PUSH_PROMISE frames.

parse_body(data)¶

Given the body of a frame, parses it into frame data. This populates the non-header parts of the frame: that is, it does not populate the stream ID or flags.

Parameters:	data – A bytestring containing the body data of the frame. Must not contain more data than the length returned by `parse_frame_header`.

promised_stream_id = None¶: The stream ID that is promised by this frame.

type = 5¶: The type byte defined for PUSH_PROMISE frames.

class hyperframe.frame.PingFrame(stream_id=0, opaque_data=b'', **kwargs)¶

Bases: hyperframe.frame.Frame

The PING frame is a mechanism for measuring a minimal round-trip time from the sender, as well as determining whether an idle connection is still functional. PING frames can be sent from any endpoint.

defined_flags = [Flag(name='ACK', bit=1)]¶: The flags defined for PING frames.

opaque_data = None¶: The opaque data sent in this PING frame, as a bytestring.

parse_body(data)¶

Given the body of a frame, parses it into frame data. This populates the non-header parts of the frame: that is, it does not populate the stream ID or flags.

Parameters:	data – A bytestring containing the body data of the frame. Must not contain more data than the length returned by `parse_frame_header`.

type = 6¶: The type byte defined for PING frames.

class hyperframe.frame.GoAwayFrame(stream_id=0, last_stream_id=0, error_code=0, additional_data=b'', **kwargs)¶

Bases: hyperframe.frame.Frame

The GOAWAY frame informs the remote peer to stop creating streams on this connection. It can be sent from the client or the server. Once sent, the sender will ignore frames sent on new streams for the remainder of the connection.

additional_data = None¶: Any additional data sent in the GOAWAY.

defined_flags = []¶: The flags defined for GOAWAY frames.

error_code = None¶: The error code for connection teardown.

last_stream_id = None¶: The last stream ID definitely seen by the remote peer.

parse_body(data)¶

Given the body of a frame, parses it into frame data. This populates the non-header parts of the frame: that is, it does not populate the stream ID or flags.

Parameters:	data – A bytestring containing the body data of the frame. Must not contain more data than the length returned by `parse_frame_header`.

type = 7¶: The type byte defined for GOAWAY frames.

class hyperframe.frame.WindowUpdateFrame(stream_id, window_increment=0, **kwargs)¶

Bases: hyperframe.frame.Frame

The WINDOW_UPDATE frame is used to implement flow control.

Flow control operates at two levels: on each individual stream and on the entire connection.

Both types of flow control are hop by hop; that is, only between the two endpoints. Intermediaries do not forward WINDOW_UPDATE frames between dependent connections. However, throttling of data transfer by any receiver can indirectly cause the propagation of flow control information toward the original sender.

defined_flags = []¶: The flags defined for WINDOW_UPDATE frames.

parse_body(data)¶

Given the body of a frame, parses it into frame data. This populates the non-header parts of the frame: that is, it does not populate the stream ID or flags.

Parameters:	data – A bytestring containing the body data of the frame. Must not contain more data than the length returned by `parse_frame_header`.

type = 8¶: The type byte defined for WINDOW_UPDATE frames.

window_increment = None¶: The amount the flow control window is to be incremented.

class hyperframe.frame.HeadersFrame(stream_id, data=b'', **kwargs)¶

Bases: hyperframe.frame.Padding, hyperframe.frame.Priority, hyperframe.frame.Frame

The HEADERS frame carries name-value pairs. It is used to open a stream. HEADERS frames can be sent on a stream in the “open” or “half closed (remote)” states.

The HeadersFrame class is actually basically a data frame in this implementation, because of the requirement to control the sizes of frames. A header block fragment that doesn’t fit in an entire HEADERS frame needs to be followed with CONTINUATION frames. From the perspective of the frame building code the header block is an opaque data segment.

data = None¶: The HPACK-encoded header block.

defined_flags = [Flag(name='END_STREAM', bit=1), Flag(name='END_HEADERS', bit=4), Flag(name='PADDED', bit=8), Flag(name='PRIORITY', bit=32)]¶: The flags defined for HEADERS frames.

parse_body(data)¶

Given the body of a frame, parses it into frame data. This populates the non-header parts of the frame: that is, it does not populate the stream ID or flags.

Parameters:	data – A bytestring containing the body data of the frame. Must not contain more data than the length returned by `parse_frame_header`.

type = 1¶: The type byte defined for HEADERS frames.

class hyperframe.frame.ContinuationFrame(stream_id, data=b'', **kwargs)¶

Bases: hyperframe.frame.Frame

The CONTINUATION frame is used to continue a sequence of header block fragments. Any number of CONTINUATION frames can be sent on an existing stream, as long as the preceding frame on the same stream is one of HEADERS, PUSH_PROMISE or CONTINUATION without the END_HEADERS flag set.

Much like the HEADERS frame, hyper treats this as an opaque data frame with different flags and a different type.

data = None¶: The HPACK-encoded header block.

defined_flags = [Flag(name='END_HEADERS', bit=4)]¶: The flags defined for CONTINUATION frames.

parse_body(data)¶

Given the body of a frame, parses it into frame data. This populates the non-header parts of the frame: that is, it does not populate the stream ID or flags.

Parameters:	data – A bytestring containing the body data of the frame. Must not contain more data than the length returned by `parse_frame_header`.

type = 9¶: The type byte defined for CONTINUATION frames.

hyperframe.frame.FRAMES = {0: <class 'hyperframe.frame.DataFrame'>, 1: <class 'hyperframe.frame.HeadersFrame'>, 2: <class 'hyperframe.frame.PriorityFrame'>, 3: <class 'hyperframe.frame.RstStreamFrame'>, 4: <class 'hyperframe.frame.SettingsFrame'>, 5: <class 'hyperframe.frame.PushPromiseFrame'>, 6: <class 'hyperframe.frame.PingFrame'>, 7: <class 'hyperframe.frame.GoAwayFrame'>, 8: <class 'hyperframe.frame.WindowUpdateFrame'>, 9: <class 'hyperframe.frame.ContinuationFrame'>, 10: <class 'hyperframe.frame.AltSvcFrame'>, 11: <class 'hyperframe.frame.BlockedFrame'>}¶: FRAMES maps the type byte for each frame to the class used to represent that frame.

Exceptions¶

class hyperframe.exceptions.UnknownFrameError(frame_type, length)¶

An frame of unknown type was received.

frame_type = None¶: The type byte of the unknown frame that was received.

length = None¶: The length of the data portion of the unknown frame.