API Reference

Functions

is_temp_network_error(exc)

Return true if exc represents a potentially temporary network problem

Classes

class HTTPConnection(hostname, port=None, ssl_context=None, proxy=None)

This class encapsulates a HTTP connection.

close()

Close HTTP connection

co_sendfile(fh)

Return coroutine to send request body data from fh

fh needs to have readinto method. The method will read and transfer only as much data as necessary to complete the request body of the active request.

This method does not send any data but returns a coroutine in form of a generator. The data must then be sent by repeatedly calling next on the generator until StopIteration is raised. A next call will return normally only if not all data has been send and response data is available in the receive buffer.

connect()

Connect to the host and port specified in __init__

This method generally does not need to be called manually.

discard()

Read and discard current response body

fileno()

Return file no of underlying socket

This allows HTTPConnection instances to be used in a select call. Due to internal buffering, data may be available for reading (but not writing) even if select indicates that the socket is not currently readable.

get_current_response()

Get method and URL of active response

Return None if there is no active response.

read(len_)

Read len_ bytes of response body data

This method may return less than len_ bytes, but will return b’’ only if the response body has been read completely. Further attempts to read more data after b’’ has been returned will result in StateError being raised.

read_response()

Read response status line and headers

Return a tuple (method, url, code, message, headers).

Even for a response with empty body, the read method must be called once before the next response can be processed.

readall()

Read complete response body

response_pending()

Return True if there are still outstanding responses

This includes responses that have been partially read.

send_request(method, url, headers=None, body=None, via_cofun=False, expect100=False)

Send a new HTTP request to the server

The message body may be passed in the body argument or be sent separately using the send_data method. In the later case, body must be an integer specifying the size of the data that will be sent.

If via_cofun is True, this method does not actually send any data but returns a coroutine in form of a generator. The request data must then be sent by repeatedly calling next on the generator until StopIteration is raised. A next call will return normally only if not all data has been send and response data is available in the receive buffer.

write(buf, partial=False)

Write request body data

ExcessBodyData will be raised when attempting to send more data than required to complete the request body of the active request.

If partial is True, this method may write less than buf. The actual number of bytes written is returned.

proxy = None

a tuple (hostname, port) of the proxy server to use or None. Note that currently only CONNECT-style proxying is supported.

Exceptions

exception ConnectionClosed(msg=None)

Raised if the server unexpectedly closed the connection.

exception InvalidResponse(msg=None)

Raised if the server produced an invalid response.

exception StateError(msg=None)

Raised when attempting an operation that doesn’t make sense in the current connection state.

exception UnsupportedResponse(msg=None)

Raised if the server produced a response that we do not support (e.g. with undefined length).

exception ExcessBodyData(msg=None)

Raised when trying to send more data to the server than announced.