HTTPX2 Documentation

HTTPCore is a minimal, low-level HTTP client designed to do one thing: send HTTP requests. It provides a foundation for higher-level libraries rather than providing high-level abstractions.

Key Features:

• Sending HTTP requests.
• Thread-safe and task-safe connection pooling.
• HTTP(S) proxy and SOCKS proxy support.
• Support for HTTP/1.1 and HTTP/2.
• Both synchronous and asynchronous interfaces.
• Async backend support for asyncio and trio.

HTTPX2 is a next-generation HTTP client for Python with the following key capabilities:

• Protocol Support: Both HTTP/1.1 and HTTP/2.
• API Styles: Standard synchronous interface and full async support.
• Compatibility: Broadly requests-compatible API.
• Application Integration: Ability to make requests directly to WSGI or ASGI applications.
• Type Safety: Fully type-annotated.
• Standard Features: Includes connection pooling, keep-alive, cookie persistence, SSL verification, authentication (Basic/Digest), multipart file uploads, and proxy support.

HTTP Core is a minimal, low-level HTTP client designed to do one thing: send HTTP requests.

Key Features:

• Thread-safe / task-safe connection pooling.
• HTTP(S) proxy & SOCKS proxy support.
• Supports HTTP/1.1 and HTTP/2.
• Provides both sync and async interfaces (supporting asyncio and trio).

What it does NOT do: It does not provide high-level abstractions. It does not handle:

• Redirects
• Multipart uploads
• Authentication header building
• Transparent HTTP caching
• URL parsing
• Session cookie handling
• Content/charset decoding or JSON handling

When to use it:

• You are building a low-level tool like a proxy service.
• You are building a higher-level library (like httpx) and need a reusable networking foundation.

When NOT to use it:

• For most application development, you should use a higher-level client library like httpx instead.

HTTPX2 uses the mounts argument for proxying and transport routing instead of the proxies dictionary used in requests. When using httpx2.Client(mounts={...}), use full URL schemes (e.g., http:// or https://).

Note that httpx2.Client.request(...) does not accept a mounts parameter; configuration must be done at the client level.

# Example of mapping schemes to transports
client = httpx2.Client(mounts={"http://": ..., "https://": ...})

For any production use case beyond simple prototyping, use a Client instance instead of the top-level API. A Client implements HTTP connection pooling, allowing it to reuse underlying TCP connections for multiple requests to the same host. This reduces latency (no handshaking), lowers CPU usage, and decreases network congestion.

httpx2.Client() is the equivalent of requests.Session() in the requests library.

import httpx2

# Recommended: Use as a context manager to ensure connection cleanup
with httpx2.Client() as client:
    r = client.get('https://example.com')

# Alternative: Explicitly close the connection pool
client = httpx2.Client()
try:
    r = client.get('https://example.com')
finally:
    client.close()

The httpcore request/response API uses a simple core model (status code, headers, and stream). To handle non-trivial or protocol-specific features without bloating the core API, httpcore uses 'extensions'.

Extensions are implemented as a dict of optional additional information. They can be passed in the extensions argument of a request or accessed via the .extensions attribute on a response object.

# Request with extensions
r = httpcore.request(
    "GET",
    "https://www.example.com",
    extensions={"timeout": {"connect": 5.0}}
)

# Accessing response extensions
print(r.extensions["http_version"])

By default, HTTPX2 uses environment variables for configuration (such as proxies and SSL certificates). To ignore these environment variables and use only the explicit configuration provided in your code, set trust_env=False.

You can disable environment variable lookup in two ways:

1. When initializing a client: httpx2.Client(trust_env=False).
2. When using the top-level API: httpx2.get("<url>", trust_env=False).

import httpx2

# Using the top-level API with trust_env=False to ignore environment variables
httpx2.get('http://example.com', trust_env=False)

# Using a Client with trust_env=False
with httpx2.Client(trust_env=False) as client:
    client.get('http://example.com')

When using a proxy, the request is handled in one of two ways:

• Forwarding: The proxy server makes the actual request to the destination server on your behalf and returns the response to you.
• Tunnelling (HTTP Tunnel): The proxy establishes a TCP connection to the destination server. The client then uses this connection to send its own request and receive the response. This is the mechanism used to access HTTPS websites through an HTTP proxy, as it allows the client to perform a TLS handshake directly with the destination server over the established TCP tunnel.

A network backend is the API layer where httpcore interacts with the network. It handles low-level operations like opening TCP connections, socket stream operations (reading, writing, closing), and SSL/TLS upgrades.

By default, httpcore automatically selects an appropriate backend, but you can explicitly provide one when initializing a ConnectionPool or AsyncConnectionPool using the network_backend argument. This allows you to switch between synchronous, asynchronous, mock, or custom implementations depending on your runtime context.

import httpcore

# Explicitly selecting a synchronous backend
network_backend = httpcore.SyncBackend()
with httpcore.ConnectionPool(network_backend=network_backend) as http:
    response = http.request('GET', 'https://www.example.com')

For asynchronous programming, use the Async prefixed versions of the core components:

• httpcore.AsyncConnectionPool: An asynchronous connection pool.
• httpcore.AsyncHTTPConnection: The base async connection class.
• httpcore.AsyncHTTP11Connection: Async support for HTTP/1.1.
• httpcore.AsyncHTTP2Connection: Async support for HTTP/2.