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().
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.
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