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 theaclose()
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
-
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 theaclose()
method.
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 anAF_INET
address (IPv4), while usinglocal_address="::"
will connect using anAF_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 theclose()
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]
-
-
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 theclose()
method.
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 anAF_INET
address (IPv4), while usinglocal_address="::"
will connect using anAF_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.