0
# aiohttp-socks
1

2
A proxy connector for aiohttp supporting SOCKS4, SOCKS4a, SOCKS5, SOCKS5h, and HTTP tunneling proxies with proxy chaining capabilities. Built on python-socks for core proxy functionality with seamless aiohttp integration.
3

4
## Package Information
5

6
- **Package Name**: aiohttp-socks  
7
- **Language**: Python
8
- **Installation**: `pip install aiohttp-socks`
9

10
## Core Imports
11

12
```python
13
from aiohttp_socks import ProxyConnector, ChainProxyConnector, ProxyType, ProxyInfo
14
```
15

16
Import exceptions for error handling:
17

18
```python
19
from aiohttp_socks import ProxyError, ProxyConnectionError, ProxyTimeoutError
20
```
21

22
## Basic Usage
23

24
```python
25
import aiohttp
26
from aiohttp_socks import ProxyConnector, ProxyType
27

28
async def fetch_with_proxy(url):
29
    # Create connector from URL
30
    connector = ProxyConnector.from_url('socks5://user:password@127.0.0.1:1080')
31
    
32
    # Or create connector with parameters
33
    # connector = ProxyConnector(
34
    #     proxy_type=ProxyType.SOCKS5,
35
    #     host='127.0.0.1',
36
    #     port=1080,
37
    #     username='user',
38
    #     password='password',
39
    #     rdns=True
40
    # )
41
    
42
    async with aiohttp.ClientSession(connector=connector) as session:
43
        async with session.get(url) as response:
44
            return await response.text()
45

46
# Proxy chaining example
47
from aiohttp_socks import ChainProxyConnector
48

49
async def fetch_with_proxy_chain(url):
50
    connector = ChainProxyConnector.from_urls([
51
        'socks5://user:password@127.0.0.1:1080',
52
        'socks4://127.0.0.1:1081',
53
        'http://user:password@127.0.0.1:3128',
54
    ])
55
    
56
    async with aiohttp.ClientSession(connector=connector) as session:
57
        async with session.get(url) as response:
58
            return await response.text()
59
```
60

61
## Architecture
62

63
The library provides two main connector classes that extend aiohttp's TCPConnector:
64

65
- **ProxyConnector**: Single proxy connection with support for all major proxy types
66
- **ChainProxyConnector**: Multiple proxy routing through a sequence of proxy servers
67
- **ProxyInfo**: Data structure for proxy configuration used in chaining
68

69
Both connectors handle authentication, SSL contexts, and integrate seamlessly with aiohttp's connector architecture using a custom resolver to bypass DNS resolution.
70

71
## Capabilities
72

73
### Single Proxy Connection
74

75
Direct proxy connections supporting SOCKS4/4a/5/5h and HTTP tunneling with authentication and SSL support.
76

77
```python { .api }
78
class ProxyConnector:
79
    def __init__(
80
        self,
81
        host: str,
82
        port: int,
83
        proxy_type: ProxyType = ProxyType.SOCKS5,
84
        username: Optional[str] = None,
85
        password: Optional[str] = None,
86
        rdns: Optional[bool] = None,
87
        proxy_ssl: Optional[SSLContext] = None,
88
        **kwargs: Any
89
    ) -> None: ...
90
    
91
    @classmethod
92
    def from_url(cls, url: str, **kwargs: Any) -> 'ProxyConnector': ...
93
```
94

95
[Proxy Connectors](./proxy-connectors.md)
96

97
### Proxy Chaining
98

99
Sequential proxy routing through multiple proxy servers for enhanced anonymity and flexible network routing.
100

101
```python { .api }
102
class ChainProxyConnector:
103
    def __init__(self, proxy_infos: Iterable[ProxyInfo], **kwargs): ...
104
    
105
    @classmethod
106
    def from_urls(cls, urls: Iterable[str], **kwargs: Any) -> 'ChainProxyConnector': ...
107

108
class ProxyInfo(NamedTuple):
109
    proxy_type: ProxyType
110
    host: str
111
    port: int
112
    username: Optional[str] = None
113
    password: Optional[str] = None
114
    rdns: Optional[bool] = None
115
```
116

117
[Proxy Chaining](./proxy-chaining.md)
118

119
### Error Handling
120

121
Comprehensive exception hierarchy for proxy connection failures and timeout handling.
122

123
```python { .api }
124
class ProxyError(Exception): ...
125
class ProxyConnectionError(ProxyError): ...  
126
class ProxyTimeoutError(ProxyError): ...
127
```
128

129
[Error Handling](./error-handling.md)
130

131
### Deprecated API
132

133
Legacy functionality maintained for backward compatibility including deprecated utility functions and connector classes.
134

135
```python { .api }
136
async def open_connection(...): ...
137
async def create_connection(...): ...
138

139
class SocksConnector(ProxyConnector): ...
140
class SocksVer: ...
141

142
SocksError = ProxyError
143
SocksConnectionError = ProxyConnectionError
144
```
145

146
[Deprecated API](./deprecated-api.md)
147

148
## Types
149

150
```python { .api }
151
# Package constants
152
__title__: str = 'aiohttp-socks'
153
__version__: str = '0.10.1'
154

155
# Proxy types
156
from python_socks import ProxyType
157
# ProxyType.SOCKS4, ProxyType.SOCKS4a, ProxyType.SOCKS5, ProxyType.SOCKS5h, ProxyType.HTTP
158

159
# Type imports
160
from ssl import SSLContext
161
from typing import Optional, Any, Iterable, NamedTuple
162
```