Proxy connector for aiohttp

0.11.0 · active · verified Sat Apr 11

The `aiohttp-socks` package extends `aiohttp` by providing a proxy connector. It supports SOCKS4(a), SOCKS5(h), and HTTP (CONNECT) proxies, as well as proxy chaining, by leveraging the `python-socks` library for core proxy functionality. The current version is 0.11.0 and it maintains compatibility with recent `aiohttp` versions.

Warnings

gotcha For SOCKS5 proxies, if connection issues (e.g., 'Connection refused') occur, ensure reverse DNS (rDNS) is enabled. This can be done by passing `rdns=True` to the `ProxyConnector` constructor or by using the `socks5h://` scheme in the proxy URL for `from_url`.
Fix: When using `ProxyConnector.from_url('socks5://...')`, change to `ProxyConnector.from_url('socks5h://...')`. Alternatively, when using the constructor, ensure `rdns=True` is set: `ProxyConnector(proxy_type=ProxyType.SOCKS5, host='...', port=..., rdns=True)`.
breaking `aiohttp-socks` does not support setting a different proxy per request within a single `aiohttp.ClientSession`. The `ProxyConnector` is static for the session it's attached to. Attempting to pass a `proxy` argument to `session.get()` or similar methods will bypass `aiohttp-socks` or not work as expected.
Fix: To use different proxies for different requests, create a new `aiohttp.ClientSession` with a new `ProxyConnector` for each unique proxy configuration required.
gotcha Older documentation or examples might refer to `SocksConnector` for creating proxy connections. The current and recommended class is `ProxyConnector`.
Fix: Always use `from aiohttp_socks import ProxyConnector` and instantiate `ProxyConnector` or `ChainProxyConnector` for new code.
breaking The minimum required Python version is 3.8 and `aiohttp` must be at least version 3.10.0. Using older versions can lead to `ImportError` or runtime incompatibilities.
Fix: Ensure your environment meets the minimum requirements: `Python >= 3.8` and `aiohttp >= 3.10.0`.

Install

pip install aiohttp-socks Install latest version

Imports

ProxyConnector
```
from aiohttp_socks import ProxyConnector
```
While `SocksConnector` might appear in older examples or versions, `ProxyConnector` is the current and recommended class for instantiating proxy connections.

ChainProxyConnector

from aiohttp_socks import ChainProxyConnector

ProxyType
```
from aiohttp_socks import ProxyType
```

Quickstart

This quickstart demonstrates how to configure an `aiohttp.ClientSession` to route requests through a SOCKS5 proxy using `ProxyConnector.from_url`. The proxy URL is retrieved from an environment variable for safe credentials handling. Ensure a proxy server is running at the specified address and port.

import aiohttp
import asyncio
import os
from aiohttp_socks import ProxyType, ProxyConnector

async def fetch_with_proxy(url):
    # Get proxy URL from environment variable for security and flexibility
    # Example: socks5://user:password@127.0.0.1:1080
    proxy_url = os.environ.get('AIOHTTP_SOCKS_PROXY_URL', 'socks5://127.0.0.1:1080')
    
    connector = ProxyConnector.from_url(proxy_url)
    
    async with aiohttp.ClientSession(connector=connector) as session:
        async with session.get(url) as response:
            response.raise_for_status()
            text = await response.text()
            print(f"Fetched via proxy: {url}\nStatus: {response.status}\nContent snippet: {text[:200]}...")

async def main():
    print("Attempting to fetch with proxy...")
    await fetch_with_proxy('http://httpbin.org/ip') # Use a simple endpoint to show IP

if __name__ == '__main__':
    asyncio.run(main())

view raw JSON →