Developer Interface

Async API Overview

Base async interfaces

These classes provide the base interface which transport classes need to implement.

class httpcore.AsyncHTTPTransport[source]

The base interface for sending HTTP requests.

Concrete implementations should subclass this class, and implement the arequest() method, and optionally the aclose() method.

async arequest(method, url, headers=None, stream=None, ext=None)[source]

The interface for sending a single HTTP request, and returning a response.

Parameters

  • method (bytes) – The HTTP method, such as b'GET'.

  • url (Tuple[bytes, bytes, Optional[int], bytes]) – The URL as a 4-tuple of (scheme, host, port, path).

  • headers (Optional[List[Tuple[bytes, bytes]]]) – Any HTTP headers to send with the request.

  • stream (Optional[httpcore.AsyncByteStream]) – The body of the HTTP request.

  • ext (Optional[dict]) – A dictionary of optional extensions.

Returns

  • status_code – The HTTP status code, such as 200.

  • headers – Any HTTP headers included on the response.

  • stream – The body of the HTTP response.

  • ext – A dictionary of optional extensions.

Return type

Tuple[int, List[Tuple[bytes, bytes]], httpcore.AsyncByteStream, dict]

async aclose()[source]

Close the implementation, which should close any outstanding response streams, and any keep alive connections.

Return type

None

class httpcore.AsyncByteStream[source]

The base interface for request and response bodies.

Concrete implementations should subclass this class, and implement the __aiter__() method, and optionally the aclose() method.

__aiter__()[source]

Yield bytes representing the request or response body.

Return type

AsyncIterator[bytes]

async aclose()[source]

Must be called by the client to indicate that the stream has been closed.

Return type

None

Async connection pool

class httpcore.AsyncConnectionPool(ssl_context=None, max_connections=None, max_keepalive_connections=None, keepalive_expiry=None, http2=False, uds=None, local_address=None, retries=0, max_keepalive=None, backend='auto')[source]

Bases: httpcore.AsyncHTTPTransport

A connection pool for making HTTP requests.

Parameters

  • ssl_context – An SSL context to use for verifying connections.

  • max_connections – The maximum number of concurrent connections to allow.

  • max_keepalive_connections – The maximum number of connections to allow before closing keep-alive connections.

  • keepalive_expiry – The maximum time to allow before closing a keep-alive connection.

  • http2 – Enable HTTP/2 support.

  • uds – Path to a Unix Domain Socket to use instead of TCP sockets.

  • local_address – Local address to connect from. Can also be used to connect using a particular address family. Using local_address="0.0.0.0" will connect using an AF_INET address (IPv4), while using local_address="::" will connect using an AF_INET6 address (IPv6).

  • retries – The maximum number of retries when trying to establish a connection.

  • backend – A name indicating which concurrency backend to use.

Async proxy

class httpcore.AsyncHTTPProxy(proxy_url, proxy_headers=None, proxy_mode='DEFAULT', ssl_context=None, max_connections=None, max_keepalive_connections=None, keepalive_expiry=None, http2=False, backend='auto', max_keepalive=None)[source]

Bases: httpcore.AsyncConnectionPool

A connection pool for making HTTP requests via an HTTP proxy.

Parameters

  • proxy_url – The URL of the proxy service as a 4-tuple of (scheme, host, port, path).

  • proxy_headers – A list of proxy headers to include.

  • proxy_mode – A proxy mode to operate in. May be “DEFAULT”, “FORWARD_ONLY”, or “TUNNEL_ONLY”.

  • ssl_context – An SSL context to use for verifying connections.

  • max_connections – The maximum number of concurrent connections to allow.

  • max_keepalive_connections – The maximum number of connections to allow before closing keep-alive connections.

  • http2 – Enable HTTP/2 support.

Async byte streams

These classes are concrete implementations of AsyncByteStream.

class httpcore.PlainByteStream(content)[source]

Bases: httpcore.AsyncByteStream, httpcore.SyncByteStream

A concrete implementation for either sync or async byte streams.

Example:

stream = httpcore.PlainByteStream(b"123")
Parameters

content – A plain byte string used as the content of the stream.

class httpcore.AsyncIteratorByteStream(aiterator, aclose_func=None)[source]

Bases: httpcore.AsyncByteStream

A concrete implementation for async byte streams.

Example:

async def generate_content():
    yield b"Hello, world!"
    ...

stream = httpcore.AsyncIteratorByteStream(generate_content())
Parameters

  • aiterator – An async byte iterator, used as the content of the stream.

  • aclose_func – An optional async function called when closing the stream.

Sync API Overview

Base sync interfaces

These classes provide the base interface which transport classes need to implement.

class httpcore.SyncHTTPTransport[source]

The base interface for sending HTTP requests.

Concrete implementations should subclass this class, and implement the request() method, and optionally the close() method.

request(method, url, headers=None, stream=None, ext=None)[source]

The interface for sending a single HTTP request, and returning a response.

Parameters

  • method (bytes) – The HTTP method, such as b'GET'.

  • url (Tuple[bytes, bytes, Optional[int], bytes]) – The URL as a 4-tuple of (scheme, host, port, path).

  • headers (Optional[List[Tuple[bytes, bytes]]]) – Any HTTP headers to send with the request.

  • stream (Optional[httpcore.SyncByteStream]) – The body of the HTTP request.

  • ext (Optional[dict]) – A dictionary of optional extensions.

Returns

  • status_code – The HTTP status code, such as 200.

  • headers – Any HTTP headers included on the response.

  • stream – The body of the HTTP response.

  • ext – A dictionary of optional extensions.

Return type

Tuple[int, List[Tuple[bytes, bytes]], httpcore.SyncByteStream, dict]

close()[source]

Close the implementation, which should close any outstanding response streams, and any keep alive connections.

Return type

None

class httpcore.SyncByteStream[source]

The base interface for request and response bodies.

Concrete implementations should subclass this class, and implement the __iter__() method, and optionally the close() method.

__iter__()[source]

Yield bytes representing the request or response body.

Return type

Iterator[bytes]

close()[source]

Must be called by the client to indicate that the stream has been closed.

Return type

None

Sync connection pool

class httpcore.SyncConnectionPool(ssl_context=None, max_connections=None, max_keepalive_connections=None, keepalive_expiry=None, http2=False, uds=None, local_address=None, retries=0, max_keepalive=None, backend='sync')[source]

Bases: httpcore.SyncHTTPTransport

A connection pool for making HTTP requests.

Parameters

  • ssl_context – An SSL context to use for verifying connections.

  • max_connections – The maximum number of concurrent connections to allow.

  • max_keepalive_connections – The maximum number of connections to allow before closing keep-alive connections.

  • keepalive_expiry – The maximum time to allow before closing a keep-alive connection.

  • http2 – Enable HTTP/2 support.

  • uds – Path to a Unix Domain Socket to use instead of TCP sockets.

  • local_address – Local address to connect from. Can also be used to connect using a particular address family. Using local_address="0.0.0.0" will connect using an AF_INET address (IPv4), while using local_address="::" will connect using an AF_INET6 address (IPv6).

  • retries – The maximum number of retries when trying to establish a connection.

  • backend – A name indicating which concurrency backend to use.

Sync proxy

class httpcore.SyncHTTPProxy(proxy_url, proxy_headers=None, proxy_mode='DEFAULT', ssl_context=None, max_connections=None, max_keepalive_connections=None, keepalive_expiry=None, http2=False, backend='sync', max_keepalive=None)[source]

Bases: httpcore.SyncConnectionPool

A connection pool for making HTTP requests via an HTTP proxy.

Parameters

  • proxy_url – The URL of the proxy service as a 4-tuple of (scheme, host, port, path).

  • proxy_headers – A list of proxy headers to include.

  • proxy_mode – A proxy mode to operate in. May be “DEFAULT”, “FORWARD_ONLY”, or “TUNNEL_ONLY”.

  • ssl_context – An SSL context to use for verifying connections.

  • max_connections – The maximum number of concurrent connections to allow.

  • max_keepalive_connections – The maximum number of connections to allow before closing keep-alive connections.

  • http2 – Enable HTTP/2 support.

Sync byte streams

These classes are concrete implementations of SyncByteStream.

class httpcore.PlainByteStream(content)[source]

Bases: httpcore.AsyncByteStream, httpcore.SyncByteStream

A concrete implementation for either sync or async byte streams.

Example:

stream = httpcore.PlainByteStream(b"123")
Parameters

content – A plain byte string used as the content of the stream.

class httpcore.IteratorByteStream(iterator, close_func=None)[source]

Bases: httpcore.SyncByteStream

A concrete implementation for sync byte streams.

Example:

def generate_content():
    yield b"Hello, world!"
    ...

stream = httpcore.IteratorByteStream(generate_content())
Parameters

  • iterator – A sync byte iterator, used as the content of the stream.

  • close_func – An optional function called when closing the stream.