0
# Proxy Connectors
1

2
Single proxy connection functionality providing support for SOCKS4, SOCKS4a, SOCKS5, SOCKS5h, and HTTP tunneling proxies with authentication and SSL support.
3

4
## Capabilities
5

6
### ProxyConnector Class
7

8
The main connector class for single proxy connections, extending aiohttp's TCPConnector with proxy support.
9

10
```python { .api }
11
class ProxyConnector:
12
    def __init__(
13
        self,
14
        host: str,
15
        port: int,
16
        proxy_type: ProxyType = ProxyType.SOCKS5,
17
        username: Optional[str] = None,
18
        password: Optional[str] = None,
19
        rdns: Optional[bool] = None,
20
        proxy_ssl: Optional[SSLContext] = None,
21
        **kwargs: Any
22
    ) -> None:
23
        """
24
        Create a proxy connector for aiohttp.
25
        
26
        Args:
27
            host (str): Proxy server hostname or IP address
28
            port (int): Proxy server port number  
29
            proxy_type (ProxyType): Type of proxy (SOCKS4/4a/5/5h/HTTP)
30
            username (str, optional): Username for proxy authentication
31
            password (str, optional): Password for proxy authentication
32
            rdns (bool, optional): Enable remote DNS resolution (default True for SOCKS5)
33
            proxy_ssl (SSLContext, optional): SSL context for proxy connection
34
            **kwargs: Additional arguments passed to TCPConnector
35
        """
36
```
37

38
#### Usage Examples
39

40
```python
41
import aiohttp
42
from aiohttp_socks import ProxyConnector, ProxyType
43

44
# Basic SOCKS5 proxy
45
connector = ProxyConnector(
46
    proxy_type=ProxyType.SOCKS5,
47
    host='127.0.0.1',
48
    port=1080
49
)
50

51
# Authenticated SOCKS5 proxy with remote DNS
52
connector = ProxyConnector(
53
    proxy_type=ProxyType.SOCKS5,
54
    host='proxy.example.com',
55
    port=1080,
56
    username='user',
57
    password='pass',
58
    rdns=True
59
)
60

61
# HTTP proxy with SSL context
62
import ssl
63
ssl_context = ssl.create_default_context()
64
connector = ProxyConnector(
65
    proxy_type=ProxyType.HTTP,
66
    host='proxy.example.com', 
67
    port=3128,
68
    proxy_ssl=ssl_context
69
)
70

71
# Use with aiohttp
72
async with aiohttp.ClientSession(connector=connector) as session:
73
    async with session.get('http://httpbin.org/ip') as response:
74
        data = await response.json()
75
        print(data)
76
```
77

78
### URL-based Connector Creation
79

80
Create connectors directly from proxy URL strings for convenient configuration.
81

82
```python { .api }
83
@classmethod
84
def from_url(cls, url: str, **kwargs: Any) -> 'ProxyConnector':
85
    """
86
    Create ProxyConnector from proxy URL.
87
    
88
    Args:
89
        url (str): Proxy URL in format: protocol://[username:password@]host:port
90
        **kwargs: Additional arguments passed to constructor
91
        
92
    Returns:
93
        ProxyConnector: Configured connector instance
94
        
95
    Supported URL formats:
96
        - socks4://proxy.example.com:1080
97
        - socks4a://user:pass@proxy.example.com:1080  
98
        - socks5://user:pass@proxy.example.com:1080
99
        - socks5h://proxy.example.com:1080
100
        - http://user:pass@proxy.example.com:3128
101
    """
102
```
103

104
#### Usage Examples
105

106
```python
107
from aiohttp_socks import ProxyConnector
108

109
# Various proxy URL formats
110
connectors = [
111
    ProxyConnector.from_url('socks5://127.0.0.1:1080'),
112
    ProxyConnector.from_url('socks5://user:password@proxy.example.com:1080'),
113
    ProxyConnector.from_url('socks4a://proxy.example.com:1080'),
114
    ProxyConnector.from_url('http://user:password@proxy.example.com:3128'),
115
]
116

117
# Use with custom TCPConnector arguments
118
connector = ProxyConnector.from_url(
119
    'socks5://proxy.example.com:1080',
120
    limit=30,
121
    ttl_dns_cache=60
122
)
123
```
124

125
### Supported Proxy Types
126

127
The library supports all major proxy protocols through the ProxyType enumeration:
128

129
- **ProxyType.SOCKS4**: SOCKS version 4 protocol
130
- **ProxyType.SOCKS4a**: SOCKS4 with hostname resolution support  
131
- **ProxyType.SOCKS5**: Full SOCKS version 5 protocol
132
- **ProxyType.SOCKS5h**: SOCKS5 with remote hostname resolution
133
- **ProxyType.HTTP**: HTTP CONNECT tunneling proxy
134

135
Each proxy type has specific capabilities for authentication and DNS resolution handling.