Interface

This section of the documentation covers the interface portions of hyper.

Primary HTTP/2 Interface

class hyper.HTTP20Connection(host, port=None, window_manager=None, enable_push=False, **kwargs)

An object representing a single HTTP/2 connection to a server.

This object behaves similarly to the Python standard library’s HTTPConnection object, with a few critical differences.

Most of the standard library’s arguments to the constructor are irrelevant for HTTP/2 or not supported by hyper.

Parameters:
  • host – The host to connect to. This may be an IP address or a hostname, and optionally may include a port: for example, 'twitter.com', 'twitter.com:443' or '127.0.0.1'.
  • port – (optional) The port to connect to. If not provided and one also isn’t provided in the host parameter, defaults to 443.
  • window_manager – (optional) The class to use to manage flow control windows. This needs to be a subclass of the BaseFlowControlManager. If not provided, FlowControlManager will be used.
  • enable_push – (optional) Whether the server is allowed to push resources to the client (see getpushes()).
close()

Close the connection to the server.

Returns:Nothing.
connect()

Connect to the server specified when the object was created. This is a no-op if we’re already connected.

Returns:Nothing.
endheaders(message_body=None, final=False, stream_id=None)

Sends the prepared headers to the server. If the message_body argument is provided it will also be sent to the server as the body of the request, and the stream will immediately be closed. If the final argument is set to True, the stream will also immediately be closed: otherwise, the stream will be left open and subsequent calls to send() will be required.

Parameters:
  • message_body – (optional) The body to send. May not be provided assuming that send() will be called.
  • final – (optional) If the message_body parameter is provided, should be set to True if no further data will be provided via calls to send().
  • stream_id – (optional) The stream ID of the request to finish sending the headers on.
Returns:

Nothing.

getpushes(stream_id=None, capture_all=False)

Returns a generator that yields push promises from the server. Note that this method is not idempotent: promises returned in one call will not be returned in subsequent calls. Iterating through generators returned by multiple calls to this method simultaneously results in undefined behavior.

Parameters:
  • stream_id – (optional) The stream ID of the request for which to get push promises.
  • capture_all – (optional) If False, the generator will yield all buffered push promises without blocking. If True, the generator will first yield all buffered push promises, then yield additional ones as they arrive, and terminate when the original stream closes.
Returns:

A generator of HTTP20Push objects corresponding to the streams pushed by the server.

getresponse(stream_id=None)

Should be called after a request is sent to get a response from the server. If sending multiple parallel requests, pass the stream ID of the request whose response you want. Returns a HTTP20Response instance. If you pass no stream_id, you will receive the oldest HTTPResponse still outstanding.

Parameters:stream_id – (optional) The stream ID of the request for which to get a response.
Returns:A HTTP20Response object.
network_buffer_size = None

The size of the in-memory buffer used to store data from the network. This is used as a performance optimisation. Increase buffer size to improve performance: decrease it to conserve memory. Defaults to 64kB.

putheader(header, argument, stream_id=None)

Sends an HTTP header to the server, with name header and value argument.

Unlike the httplib version of this function, this version does not actually send anything when called. Instead, it queues the headers up to be sent when you call endheaders().

This method ensures that headers conform to the HTTP/2 specification. In particular, it strips out the Connection header, as that header is no longer valid in HTTP/2. This is to make it easy to write code that runs correctly in both HTTP/1.1 and HTTP/2.

Parameters:
  • header – The name of the header.
  • argument – The value of the header.
  • stream_id – (optional) The stream ID of the request to add the header to.
Returns:

Nothing.

putrequest(method, selector, **kwargs)

This should be the first call for sending a given HTTP request to a server. It returns a stream ID for the given connection that should be passed to all subsequent request building calls.

Parameters:
  • method – The request method, e.g. 'GET'.
  • selector – The path selector.
Returns:

A stream ID for the request.

receive_frame(frame)

Handles receiving frames intended for the stream.

request(method, url, body=None, headers={})

This will send a request to the server using the HTTP request method method and the selector url. If the body argument is present, it should be string or bytes object of data to send after the headers are finished. Strings are encoded as UTF-8. To use other encodings, pass a bytes object. The Content-Length header is set to the length of the body field.

Parameters:
  • method – The request method, e.g. 'GET'.
  • url – The URL to contact, e.g. '/path/segment'.
  • body – (optional) The request body to send. Must be a bytestring or a file-like object.
  • headers – (optional) The headers to send on the request.
Returns:

A stream ID for the request.

send(data, final=False, stream_id=None)

Sends some data to the server. This data will be sent immediately (excluding the normal HTTP/2 flow control rules). If this is the last data that will be sent as part of this request, the final argument should be set to True. This will cause the stream to be closed.

Parameters:
  • data – The data to send.
  • final – (optional) Whether this is the last bit of data to be sent on this request.
  • stream_id – (optional) The stream ID of the request to send the data on.
Returns:

Nothing.

class hyper.HTTP20Response(headers, stream)

An HTTP20Response wraps the HTTP/2 response from the server. It provides access to the response headers and the entity body. The response is an iterable object and can be used in a with statement (though due to the persistent connections used in HTTP/2 this has no effect, and is done soley for compatibility).

close()

Close the response. In effect this closes the backing HTTP/2 stream.

Returns:Nothing.
fileno()

Return the fileno of the underlying socket. This function is currently not implemented.

getheader(name, default=None)

Return the value of the header name, or default if there is no header matching name. If there is more than one header with the value name, return all of the values joined by ‘, ‘. If default is any iterable other than a single string, its elements are similarly returned joined by commas.

Parameters:
  • name – The name of the header to get the value of.
  • default – (optional) The return value if the header wasn’t sent.
Returns:

The value of the header.

getheaders()

Get all the headers sent on the response.

Returns:A list of (header, value) tuples.
gettrailer(name, default=None)

Return the value of the trailer name, or default if there is no trailer matching name. If there is more than one trailer with the value name, return all of the values joined by ‘, ‘. If default is any iterable other than a single string, its elements are similarly returned joined by commas.

Warning

Note that this method requires that the stream is totally exhausted. This means that, if you have not completely read from the stream, all stream data will be read into memory.

Parameters:
  • name – The name of the trailer to get the value of.
  • default – (optional) The return value if the trailer wasn’t sent.
Returns:

The value of the trailer.

gettrailers()

Get all the trailers sent on the response.

Warning

Note that this method requires that the stream is totally exhausted. This means that, if you have not completely read from the stream, all stream data will be read into memory.

Returns:A list of (header, value) tuples.
read(amt=None, decode_content=True)

Reads the response body, or up to the next amt bytes.

Parameters:
  • amt – (optional) The amount of data to read. If not provided, all the data will be read from the response.
  • decode_content – (optional) If True, will transparently decode the response data.
Returns:

The read data. Note that if decode_content is set to True, the actual amount of data returned may be different to the amount requested.

reason = None

The reason phrase returned by the server. This is not used in HTTP/2, and so is always the empty string.

status = None

The status code returned by the server.

class hyper.HTTP20Push(request_headers, stream)

Represents a request-response pair sent by the server through the server push mechanism.

authority = None

The authority of the simulated request (usually host:port)

cancel()

Cancel the pushed response and close the stream.

Returns:Nothing.
getrequestheader(name, default=None)

Return the value of the simulated request header name, or default if there is no header matching name. If there is more than one header with the value name, return all of the values joined by ', '. If default is any iterable other than a single string, its elements are similarly returned joined by commas.

Parameters:
  • name – The name of the header to get the value of.
  • default – (optional) The return value if the header wasn’t sent.
Returns:

The value of the header.

getrequestheaders()

Get all the simulated request headers.

Returns:A list of (header, value) tuples.
getresponse()

Get the pushed response provided by the server.

Returns:A HTTP20Response object representing the pushed response.
method = None

The method of the simulated request (must be safe and cacheable, e.g. GET)

path = None

The path of the simulated request

scheme = None

The scheme of the simulated request

Requests Transport Adapter

class hyper.contrib.HTTP20Adapter(*args, **kwargs)

A Requests Transport Adapter that uses hyper to send requests over HTTP/2. This implements some degree of connection pooling to maximise the HTTP/2 gain.

build_response(request, resp)

Builds a Requests’ response object. This emulates most of the logic of the standard fuction but deals with the lack of the .headers property on the HTTP20Response object.

Additionally, this function builds in a number of features that are purely for HTTPie. This is to allow maximum compatibility with what urllib3 does, so that HTTPie doesn’t fall over when it uses us.

connections = None

A mapping between HTTP netlocs and HTTP20Connection objects.

get_connection(netloc)

Gets an appropriate HTTP/2 connection object based on netloc.

send(request, stream=False, **kwargs)

Sends a HTTP message to the server.

Flow Control

class hyper.http20.window.BaseFlowControlManager(initial_window_size, document_size=None)

The abstract base class for flow control managers.

This class defines the interface for pluggable flow-control managers. A flow-control manager defines a flow-control policy, which basically boils down to deciding when to increase the flow control window.

This decision can be based on a number of factors:

  • the initial window size,
  • the size of the document being retrieved,
  • the size of the received data frames,
  • any other information the manager can obtain

A flow-control manager may be defined at the connection level or at the stream level. If no stream-level flow-control manager is defined, an instance of the connection-level flow control manager is used.

A class that inherits from this one must not adjust the member variables defined in this class. They are updated and set by methods on this class.

blocked()

Called whenever the remote endpoint reports that it is blocked behind the flow control window.

When this method is called the remote endpoint is signaling that it has more data to send and that the transport layer is capable of transmitting it, but that the HTTP/2 flow control window prevents it being sent.

This method should return the size by which the window should be incremented, which may be zero. This method should not adjust any of the member variables of this class.

Returns:The amount to increase the receive window by. Return zero if the window should not be increased.
document_size = None

The size of the document being retrieved, in bytes. This is retrieved from the Content-Length header, if provided. Note that the total number of bytes that will be received may be larger than this value due to HTTP/2 padding. It should not be assumed that simply because the the document size is smaller than the initial window size that there will never be a need to increase the window size.

increase_window_size(frame_size)

Determine whether or not to emit a WINDOWUPDATE frame.

This method should be overridden to determine, based on the state of the system and the size of the received frame, whether or not a WindowUpdate frame should be sent for the stream.

This method should not adjust any of the member variables of this class.

Note that this method is called before the window size is decremented as a result of the frame being handled.

Parameters:frame_size – The size of the received frame. Note that this may be zero. When this parameter is zero, it’s possible that a WINDOWUPDATE frame may want to be emitted anyway. A zero-length frame size is usually associated with a change in the size of the receive window due to a SETTINGS frame.
Returns:The amount to increase the receive window by. Return zero if the window should not be increased.
initial_window_size = None

The initial size of the connection window in bytes. This is set at creation time.

window_size = None

The current size of the connection window. Any methods overridden by the user must not adjust this value.

class hyper.http20.window.FlowControlManager(initial_window_size, document_size=None)

hyper‘s default flow control manager.

This implements hyper’s flow control algorithms. This algorithm attempts to reduce the number of WINDOWUPDATE frames we send without blocking the remote endpoint behind the flow control window.

This algorithm will become more complicated over time. In the current form, the algorithm is very simple:

  • When the flow control window gets less than 1/4 of the maximum size, increment back to the maximum.
  • Otherwise, if the flow control window gets to less than 1kB, increment back to the maximum.

Exceptions

class hyper.http20.exceptions.HTTP20Error

The base class for all of hyper‘s HTTP/2-related exceptions.

class hyper.http20.exceptions.HPACKEncodingError

An error has been encountered while performing HPACK encoding.

class hyper.http20.exceptions.HPACKDecodingError

An error has been encountered while performing HPACK decoding.

class hyper.http20.exceptions.ConnectionError

The remote party signalled an error affecting the entire HTTP/2 connection, and the connection has been closed.