urllib3-future: HTTP/1.1, 2, and 3 Client (Sync & Async)

Warnings

• gotcha Header precedence behavior was subject to confusing changes between versions 2.19.902 and 2.19.903. While the intent is for user-supplied headers to take precedence over extension defaults (e.g., for SSE), the exact behavior during this period was ambiguous due to conflicting release notes.
  Fix: For critical applications, explicitly test header behavior if upgrading from or using versions in this range. The current (2.19.903+) expectation is that user-supplied headers should take precedence, but verify for your specific use case.
• gotcha `urllib3-future` is a distinct library, not a drop-in replacement or a fork of the standard `urllib3`. While it shares similar API patterns, it may introduce differences, especially around asynchronous features, HTTP/2/3, and specific connection management. Direct compatibility is not guaranteed for all `urllib3` use cases.
  Fix: Always import as `import urllib3.future as urllib3` to clearly differentiate from the standard library. Refer to the specific `urllib3-future` documentation for API details and behavioral nuances rather than assuming parity with `urllib3`.
• gotcha The project exhibits a rapid release cadence (daily/weekly) and uses high patch version numbers (e.g., `.905`) within a `2.x` major version. This signifies active and rapid development, where minor behavioral changes or API tweaks could occur even in what appear to be 'patch' releases.
  Fix: For production deployments, pin exact package versions (`urllib3-future==X.Y.Z`) to avoid unexpected changes from new releases. Review release notes diligently for any changes that might affect your application.
• gotcha Installing the `[rtls]` extra automatically switches the underlying TLS backend to Rustls. While Rustls is lauded for memory safety and security, it is a different implementation than OpenSSL (used by default in CPython and standard `urllib3`). This may lead to subtle behavioral differences, particularly with advanced SSL/TLS configurations or specific certificate authorities.
  Fix: If encountering unexpected SSL/TLS errors or certificate issues, first test without the `[rtls]` extra. When passing `stdlib` `ssl.SSLContext` objects, be aware that the conversion to `rtls.SSLContext` is a 'best effort' as of 2.19.905 and might not perfectly map all configurations.

Install

• pip install urllib3-future Standard Install
• pip install urllib3-future[rtls] Install with Rustls TLS Backend

Imports

• AsyncConnectionPool

  import urllib3.future as urllib3
  pool = urllib3.AsyncConnectionPool(...)

  The 'urllib3.future' package is typically imported with an alias to avoid conflicts with the standard 'urllib3' package and maintain clarity. Direct import from 'urllib3' may refer to the standard library.
• ConnectionPool

  import urllib3.future as urllib3
  pool = urllib3.ConnectionPool(...)

  The 'urllib3.future' package is typically imported with an alias to avoid conflicts with the standard 'urllib3' package and maintain clarity. Direct import from 'urllib3' may refer to the standard library.
• PoolManager

  import urllib3.future as urllib3
  manager = urllib3.PoolManager(...)

  While 'PoolManager' exists, 'ConnectionPool' and 'AsyncConnectionPool' are the primary high-level interfaces highlighted in `urllib3.future` examples for direct usage.

Quickstart

Demonstrates both asynchronous and synchronous usage patterns with `AsyncConnectionPool` and `ConnectionPool` respectively, fetching data from `httpbin.org`. The async example is run via `asyncio.run()`, and the sync example is called directly.

import urllib3.future as urllib3
import asyncio
import os

# Asynchronous example
async def async_example():
    # No authentication needed for httpbin.org
    pool = urllib3.AsyncConnectionPool("https://httpbin.org")
    try:
        print("\n--- Async Example ---")
        resp = await pool.request("GET", "/get")
        print(f"Status: {resp.status}")
        # Decode data and truncate for cleaner output
        print(f"Data: {resp.data.decode('utf-8')[:200]}...")
    except Exception as e:
        print(f"Async request failed: {e}")
    finally:
        await pool.close()

# Synchronous example
def sync_example():
    pool = urllib3.ConnectionPool("https://httpbin.org")
    try:
        print("\n--- Sync Example ---")
        resp = pool.request("GET", "/get")
        print(f"Status: {resp.status}")
        print(f"Data: {resp.data.decode('utf-8')[:200]}...")
    except Exception as e:
        print(f"Sync request failed: {e}")
    finally:
        pool.close()

# Run the examples
if __name__ == "__main__":
    asyncio.run(async_example())
    sync_example() # Synchronous call, not within async loop