Skip to content

Developer Interface

Async API Overview

The AsyncHTTPTransport and AsyncByteStream classes provide the base interface which transport classes need to implement.

class httpcore.AsyncHTTPTransport()

The base interface for sending HTTP requests.

Concete implementations should subclass this class, and implement the request method, and optionally the close method.

arequest(self, method, url, headers=None, stream=None, ext=None)

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[AsyncByteStream] - The body of the HTTP request.
  • ext - Optional[dict] - A dictionary of optional extensions.

Returns:

A four-tuple of:

  • status_code - int - The HTTP status code, such as 200.
  • headers - List[Tuple[bytes, bytes]] - Any HTTP headers included on the response.
  • stream - AsyncByteStream - The body of the HTTP response.
  • ext - dict - A dictionary of optional extensions.
aclose(self)

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

class httpcore.AsyncByteStream()

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

Yield bytes representing the request or response body.

aclose(self)

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

The AsyncConnectionPool class is a concrete implementation of AsyncHTTPTransport.

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')

A connection pool for making HTTP requests.

Parameters:

  • ssl_context - Optional[SSLContext] - An SSL context to use for verifying connections.
  • max_connections - Optional[int] - The maximum number of concurrent connections to allow.
  • max_keepalive_connections - Optional[int] - The maximum number of connections to allow before closing keep-alive connections.
  • keepalive_expiry - Optional[float] - The maximum time to allow before closing a keep-alive connection.
  • http2 - bool - Enable HTTP/2 support.
  • uds - str - Path to a Unix Domain Socket to use instead of TCP sockets.
  • local_address - Optional[str] - 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 - int - The maximum number of retries when trying to establish a connection.
  • backend - str - A name indicating which concurrency backend to use.

The PlainByteStream and AsyncIteratorByteStream classes are concrete implementations of AsyncByteStream.

class httpcore.PlainByteStream(content)

A concrete implementation for either sync or async byte streams. Just handles a plain byte string as the content of the stream.

stream = httpcore.PlainByteStream(b"123")
class httpcore.AsyncIteratorByteStream(aiterator, aclose_func=None)

A concrete implementation for async byte streams. Handles an async byte iterator as the content of the stream.

async def generate_content():
    ...

stream = httpcore.AsyncIteratorByteStream(generate_content())

Sync API Overview

The SyncHTTPTransport and SyncByteStream classes provide the base interface which transport classes need to implement.

class httpcore.SyncHTTPTransport()

The base interface for sending HTTP requests.

Concete implementations should subclass this class, and implement the request method, and optionally the close method.

request(self, method, url, headers=None, stream=None, ext=None)

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[SyncByteStream] - The body of the HTTP request.
  • ext - Optional[dict] - A dictionary of optional extensions.

Returns:

A four-tuple of:

  • status_code - int - The HTTP status code, such as 200.
  • headers - List[Tuple[bytes, bytes]] - Any HTTP headers included on the response.
  • stream - SyncByteStream - The body of the HTTP response.
  • ext - dict - A dictionary of optional extensions.
close(self)

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

class httpcore.SyncByteStream()

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

Yield bytes representing the request or response body.

close(self)

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

The SyncConnectionPool class is a concrete implementation of SyncHTTPTransport.

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')

A connection pool for making HTTP requests.

Parameters:

  • ssl_context - Optional[SSLContext] - An SSL context to use for verifying connections.
  • max_connections - Optional[int] - The maximum number of concurrent connections to allow.
  • max_keepalive_connections - Optional[int] - The maximum number of connections to allow before closing keep-alive connections.
  • keepalive_expiry - Optional[float] - The maximum time to allow before closing a keep-alive connection.
  • http2 - bool - Enable HTTP/2 support.
  • uds - str - Path to a Unix Domain Socket to use instead of TCP sockets.
  • local_address - Optional[str] - 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 - int - The maximum number of retries when trying to establish a connection.
  • backend - str - A name indicating which concurrency backend to use.

The PlainByteStream and IteratorByteStream classes are concrete implementations of SyncByteStream.

class httpcore.PlainByteStream(content)

A concrete implementation for either sync or async byte streams. Just handles a plain byte string as the content of the stream.

stream = httpcore.PlainByteStream(b"123")
class httpcore.IteratorByteStream(iterator, close_func=None)

A concrete implementation for sync byte streams. Handles a byte iterator as the content of the stream.

def generate_content():
    ...

stream = httpcore.IteratorByteStream(generate_content())