Hyper-h2 API¶
This document details the API of Hyper-h2.
Semantic Versioning¶
Hyper-h2 follows semantic versioning for its public API. Please note that the guarantees of semantic versioning apply only to the API that is documented here. Simply because a method or data field is not prefaced by an underscore does not make it part of Hyper-h2’s public API. Anything not documented here is subject to change at any time.
Connection¶
Configuration¶
-
class
h2.config.
H2Configuration
(client_side=True, header_encoding=None, validate_outbound_headers=True, normalize_outbound_headers=True, validate_inbound_headers=True, normalize_inbound_headers=True, logger=None)[source]¶ An object that controls the way a single HTTP/2 connection behaves.
This object allows the users to customize behaviour. In particular, it allows users to enable or disable optional features, or to otherwise handle various unusual behaviours.
This object has very little behaviour of its own: it mostly just ensures that configuration is self-consistent.
- Parameters
client_side (
bool
) – Whether this object is to be used on the client side of a connection, or on the server side. Affects the logic used by the state machine, the default settings values, the allowable stream IDs, and several other properties. Defaults toTrue
.header_encoding (
str
,False
, orNone
) –Controls whether the headers emitted by this object in events are transparently decoded to
unicode
strings, and what encoding is used to do that decoding. This defaults toNone
, meaning that headers will be returned as bytes. To automatically decode headers (that is, to return them as unicode strings), this can be set to the string name of any encoding, e.g.'utf-8'
.Changed in version 3.0.0: Changed default value from
'utf-8'
toNone
validate_outbound_headers (
bool
) – Controls whether the headers emitted by this object are validated against the rules in RFC 7540. Disabling this setting will cause outbound header validation to be skipped, and allow the object to emit headers that may be illegal according to RFC 7540. Defaults toTrue
.normalize_outbound_headers (
bool
) – Controls whether the headers emitted by this object are normalized before sending. Disabling this setting will cause outbound header normalization to be skipped, and allow the object to emit headers that may be illegal according to RFC 7540. Defaults toTrue
.validate_inbound_headers (
bool
) – Controls whether the headers received by this object are validated against the rules in RFC 7540. Disabling this setting will cause inbound header validation to be skipped, and allow the object to receive headers that may be illegal according to RFC 7540. Defaults toTrue
.normalize_inbound_headers (
bool
) –Controls whether the headers received by this object are normalized according to the rules of RFC 7540. Disabling this setting may lead to hyper-h2 emitting header blocks that some RFCs forbid, e.g. with multiple cookie fields.
New in version 3.0.0.
logger (
logging.Logger
) –A logger that conforms to the requirements for this module, those being no I/O and no context switches, which is needed in order to run in asynchronous operation.
New in version 2.6.0.
-
property
header_encoding
¶ Controls whether the headers emitted by this object in events are transparently decoded to
unicode
strings, and what encoding is used to do that decoding. This defaults toNone
, meaning that headers will be returned as bytes. To automatically decode headers (that is, to return them as unicode strings), this can be set to the string name of any encoding, e.g.'utf-8'
.
Events¶
Exceptions¶
-
class
h2.exceptions.
NoSuchStreamError
(stream_id)[source]¶ Bases:
h2.exceptions.ProtocolError
A stream-specific action referenced a stream that does not exist.
Changed in version 2.0.0: Became a subclass of
ProtocolError
-
stream_id
¶ The stream ID that corresponds to the non-existent stream.
-
-
class
h2.exceptions.
StreamClosedError
(stream_id)[source]¶ Bases:
h2.exceptions.NoSuchStreamError
A more specific form of
NoSuchStreamError
. Indicates that the stream has since been closed, and that all state relating to that stream has been removed.-
stream_id
¶ The stream ID that corresponds to the nonexistent stream.
-
-
class
h2.exceptions.
RFC1122Error
[source]¶ Bases:
h2.exceptions.H2Error
Emitted when users attempt to do something that is literally allowed by the relevant RFC, but is sufficiently ill-defined that it’s unwise to allow users to actually do it.
While there is some disagreement about whether or not we should be liberal in what accept, it is a truth universally acknowledged that we should be conservative in what emit.
New in version 2.4.0.
Protocol Errors¶
-
class
h2.exceptions.
ProtocolError
[source]¶ Bases:
h2.exceptions.H2Error
An action was attempted in violation of the HTTP/2 protocol.
-
error_code
= 1¶ The error code corresponds to this kind of Protocol Error.
-
-
class
h2.exceptions.
FrameTooLargeError
[source]¶ Bases:
h2.exceptions.ProtocolError
The frame that we tried to send or that we received was too large.
-
error_code
= 6¶ This error code that corresponds to this kind of Protocol Error.
-
-
class
h2.exceptions.
FrameDataMissingError
[source]¶ Bases:
h2.exceptions.ProtocolError
The frame that we received is missing some data.
New in version 2.0.0.
-
error_code
= 6¶ The error code that corresponds to this kind of Protocol Error
-
-
class
h2.exceptions.
TooManyStreamsError
[source]¶ Bases:
h2.exceptions.ProtocolError
An attempt was made to open a stream that would lead to too many concurrent streams.
-
class
h2.exceptions.
FlowControlError
[source]¶ Bases:
h2.exceptions.ProtocolError
An attempted action violates flow control constraints.
-
error_code
= 3¶ The error code that corresponds to this kind of
ProtocolError
-
-
class
h2.exceptions.
StreamIDTooLowError
(stream_id, max_stream_id)[source]¶ Bases:
h2.exceptions.ProtocolError
An attempt was made to open a stream that had an ID that is lower than the highest ID we have seen on this connection.
-
max_stream_id
¶ The current highest-seen stream ID.
-
stream_id
¶ The ID of the stream that we attempted to open.
-
-
class
h2.exceptions.
InvalidSettingsValueError
(msg, error_code)[source]¶ An attempt was made to set an invalid Settings value.
New in version 2.0.0.
-
class
h2.exceptions.
NoAvailableStreamIDError
[source]¶ Bases:
h2.exceptions.ProtocolError
There are no available stream IDs left to the connection. All stream IDs have been exhausted.
New in version 2.0.0.
-
class
h2.exceptions.
InvalidBodyLengthError
(expected, actual)[source]¶ Bases:
h2.exceptions.ProtocolError
The remote peer sent more or less data that the Content-Length header indicated.
New in version 2.0.0.
-
class
h2.exceptions.
UnsupportedFrameError
[source]¶ The remote peer sent a frame that is unsupported in this context.
New in version 2.1.0.
-
class
h2.exceptions.
DenialOfServiceError
[source]¶ Bases:
h2.exceptions.ProtocolError
Emitted when the remote peer exhibits a behaviour that is likely to be an attempt to perform a Denial of Service attack on the implementation. This is a form of ProtocolError that carries a different error code, and allows more easy detection of this kind of behaviour.
New in version 2.5.0.
-
error_code
= 11¶ The error code that corresponds to this kind of
ProtocolError
-
HTTP/2 Error Codes¶
h2/errors¶
Global error code registry containing the established HTTP/2 error codes.
The current registry is available at: https://tools.ietf.org/html/rfc7540#section-11.4
-
class
h2.errors.
ErrorCodes
(value)[source]¶ All known HTTP/2 error codes.
New in version 2.5.0.
-
CANCEL
= 8¶ Stream cancelled.
-
COMPRESSION_ERROR
= 9¶ Compression state not updated.
-
CONNECT_ERROR
= 10¶ TCP connection error for CONNECT method.
-
ENHANCE_YOUR_CALM
= 11¶ Processing capacity exceeded.
-
FLOW_CONTROL_ERROR
= 3¶ Flow-control limits exceeded.
-
FRAME_SIZE_ERROR
= 6¶ Frame size incorrect.
-
HTTP_1_1_REQUIRED
= 13¶ Use HTTP/1.1 for the request.
-
INADEQUATE_SECURITY
= 12¶ Negotiated TLS parameters not acceptable.
-
INTERNAL_ERROR
= 2¶ Implementation fault.
-
NO_ERROR
= 0¶ Graceful shutdown.
-
PROTOCOL_ERROR
= 1¶ Protocol error detected.
-
REFUSED_STREAM
= 7¶ Stream not processed.
-
SETTINGS_TIMEOUT
= 4¶ Settings not acknowledged.
-
STREAM_CLOSED
= 5¶ Frame received for closed stream.
-