httpx-socks

httpx-socks provides custom transport classes that let httpx route requests through SOCKS4(a), SOCKS5(h), or HTTP CONNECT proxies. It builds on python-socks (from the same author) for the actual proxy handshake and connection logic, so httpx itself doesn’t need native proxy protocol support.

The package ships separate sync and async transport classes, with optional asyncio and trio backends, so it fits both blocking scripts and async applications using httpx’s Client/AsyncClient interfaces without changing how requests are made.

What You Get

• SyncProxyTransport and AsyncProxyTransport classes that plug directly into httpx.Client/AsyncClient
• Support for SOCKS4(a), SOCKS5(h), and HTTP CONNECT proxy protocols
• Optional asyncio and trio backends via extras (httpx-socks[asyncio], httpx-socks[trio])
• Proxy handshake logic delegated to python-socks, keeping the transport layer thin
• A from_url() constructor that parses standard proxy URLs (socks5://user:pass@host:port)

Common Use Cases

• Routing httpx requests through a SOCKS5 proxy for scraping or automation behind a residential/rotating proxy pool
• Adding HTTP CONNECT or SOCKS4 proxy support to an existing httpx-based API client
• Using proxies in async services built on asyncio or trio without swapping HTTP clients
• Testing or accessing geo-restricted APIs through a SOCKS proxy in Python scripts

Under The Hood

Architecture: the package is split into sync and async transport modules — _sync_transport.py/_sync_proxy.py implement httpx.BaseTransport, while _async_transport.py/_async_proxy.py implement httpx.AsyncBaseTransport; both delegate the actual SOCKS/CONNECT handshake to the separate python-socks package and wrap the resulting raw socket into an httpx-compatible stream (_sync_stream.py). Tech Stack: pure Python (>=3.8), depends on httpx>=0.28,<0.29 and python-socks>=2.4.3,<3.0, with optional trio and anyio extras for alternate async backends. Code Quality: the tests/ directory covers sync, asyncio, and trio transports separately (test_transport_sync.py, test_transport_asyncio.py, test_transport_trio.py) against a local mock proxy server (proxy_server.py, http_server.py), with CI and Codecov badges indicating enforced coverage. API Design: the API mirrors httpx’s own transport pattern — construct a transport with from_url() and pass it to httpx.Client(transport=...) — so adopting a proxy requires no changes to how requests are made elsewhere in the codebase.