0
# Python SOCKS
1

2
Python SOCKS provides a core proxy client functionality for Python. It supports SOCKS4(a), SOCKS5(h), and HTTP CONNECT proxy protocols with both synchronous and asynchronous APIs. The library offers native integration with multiple async frameworks including asyncio, trio, curio, and anyio, enabling developers to route network connections through proxy servers across different concurrency models.
3

4
## Package Information
5

6
- **Package Name**: python-socks
7
- **Language**: Python
8
- **Installation**: `pip install python-socks`
9
- **Optional async support**: `pip install python-socks[asyncio]`, `pip install python-socks[trio]`, `pip install python-socks[curio]`, `pip install python-socks[anyio]`
10
- **Requirements**: Python >= 3.8
11

12
## Core Imports
13

14
```python
15
from python_socks import ProxyType, ProxyError, ProxyTimeoutError, ProxyConnectionError, parse_proxy_url
16
```
17

18
Synchronous usage:
19

20
```python
21
from python_socks.sync import Proxy, ProxyChain
22
```
23

24
Asynchronous usage (by framework):
25

26
```python
27
from python_socks.async_.asyncio import Proxy as AsyncioProxy
28
from python_socks.async_.trio import Proxy as TrioProxy
29
from python_socks.async_.curio import Proxy as CurioProxy
30
from python_socks.async_.anyio import Proxy as AnyioProxy, ProxyChain as AnyioProxyChain
31
```
32

33
V2 enhanced APIs:
34

35
```python
36
from python_socks.sync.v2 import Proxy as SyncProxyV2, ProxyChain as SyncProxyChainV2
37
from python_socks.async_.asyncio.v2 import Proxy as AsyncioProxyV2, ProxyChain as AsyncioProxyChainV2
38
```
39

40
## Basic Usage
41

42
### Synchronous Example
43

44
```python
45
import ssl
46
from python_socks.sync import Proxy
47

48
# Create proxy from URL
49
proxy = Proxy.from_url('socks5://user:password@127.0.0.1:1080')
50

51
# Connect through proxy - returns standard Python socket
52
sock = proxy.connect(dest_host='check-host.net', dest_port=443)
53

54
# Use the socket normally
55
sock = ssl.create_default_context().wrap_socket(
56
    sock=sock,
57
    server_hostname='check-host.net'
58
)
59

60
request = (
61
    b'GET /ip HTTP/1.1\r\n'
62
    b'Host: check-host.net\r\n'
63
    b'Connection: close\r\n\r\n'
64
)
65
sock.sendall(request)
66
response = sock.recv(4096)
67
print(response)
68
```
69

70
### Asynchronous Example (asyncio)
71

72
```python
73
import ssl
74
import asyncio
75
from python_socks.async_.asyncio import Proxy
76

77
async def main():
78
    # Create proxy from URL
79
    proxy = Proxy.from_url('socks5://user:password@127.0.0.1:1080')
80
    
81
    # Connect through proxy - returns non-blocking socket
82
    sock = await proxy.connect(dest_host='check-host.net', dest_port=443)
83
    
84
    # Use with asyncio
85
    reader, writer = await asyncio.open_connection(
86
        host=None,
87
        port=None,
88
        sock=sock,
89
        ssl=ssl.create_default_context(),
90
        server_hostname='check-host.net',
91
    )
92
    
93
    request = (
94
        b'GET /ip HTTP/1.1\r\n'
95
        b'Host: check-host.net\r\n'
96
        b'Connection: close\r\n\r\n'
97
    )
98
    writer.write(request)
99
    await writer.drain()
100
    
101
    response = await reader.read(4096)
102
    print(response)
103
    
104
    writer.close()
105
    await writer.wait_closed()
106

107
asyncio.run(main())
108
```
109

110
## Architecture
111

112
The library is organized around proxy implementations for different concurrency models:
113

114
- **Core Layer**: Common types, errors, and helper functions shared across all implementations
115
- **Sync Layer**: Blocking socket-based proxy implementations for traditional threading models
116
- **Async Layer**: Non-blocking implementations for asyncio, trio, curio, and anyio frameworks
117
- **V2 Layer**: Enhanced implementations with additional features and improved error handling
118
- **Protocol Layer**: Internal SOCKS4, SOCKS5, and HTTP CONNECT protocol implementations
119
- **Connector Layer**: Protocol-specific connection handlers and authentication mechanisms
120

121
This modular design allows the library to serve as a foundational dependency for higher-level HTTP client libraries while providing direct access to proxy functionality across different concurrency paradigms.
122

123
## Capabilities
124

125
### Core API
126

127
Common types, exceptions, and utility functions used across all proxy implementations. Includes proxy type enumeration, error handling classes, and URL parsing functionality.
128

129
```python { .api }
130
from typing import Tuple, Optional
131
from enum import Enum
132

133
class ProxyType(Enum):
134
    SOCKS4 = 1
135
    SOCKS5 = 2  
136
    HTTP = 3
137

138
class ProxyError(Exception): ...
139
class ProxyTimeoutError(TimeoutError): ...
140
class ProxyConnectionError(OSError): ...
141

142
def parse_proxy_url(url: str) -> Tuple[ProxyType, str, int, Optional[str], Optional[str]]: ...
143
```
144

145
[Core API](./core-api.md)
146

147
### Synchronous Proxies
148

149
Blocking proxy implementations that return standard Python sockets. Supports SOCKS4, SOCKS5, and HTTP CONNECT protocols with authentication and proxy chaining capabilities.
150

151
```python { .api }
152
class Proxy:
153
    def __init__(self, proxy_type: ProxyType, host: str, port: int, 
154
                 username: Optional[str] = None, password: Optional[str] = None, 
155
                 rdns: Optional[bool] = None): ...
156
    def connect(self, dest_host: str, dest_port: int, 
157
                timeout: Optional[float] = None, **kwargs) -> socket.socket: ...
158
    @classmethod
159
    def from_url(cls, url: str, **kwargs) -> 'Proxy': ...
160
```
161

162
[Synchronous API](./sync-api.md)
163

164
### Asynchronous Proxies
165

166
Non-blocking proxy implementations for asyncio, trio, curio, and anyio frameworks. Each framework has its own optimized implementation while maintaining a consistent API interface.
167

168
```python { .api }
169
class AsyncioProxy:
170
    def __init__(self, proxy_type: ProxyType, host: str, port: int,
171
                 username: Optional[str] = None, password: Optional[str] = None,
172
                 rdns: Optional[bool] = None, loop: Optional[asyncio.AbstractEventLoop] = None): ...
173
    async def connect(self, dest_host: str, dest_port: int,
174
                      timeout: Optional[float] = None, **kwargs) -> socket.socket: ...
175
    @classmethod  
176
    def from_url(cls, url: str, **kwargs) -> 'AsyncioProxy': ...
177
```
178

179
[Asynchronous API](./async-api.md)
180

181
### Enhanced V2 API
182

183
Improved proxy implementations with enhanced error handling, SSL support, and additional configuration options. Available for both synchronous and asynchronous usage patterns.
184

185
```python { .api }
186
class SyncProxyV2:
187
    def __init__(self, proxy_type: ProxyType, host: str, port: int,
188
                 username: Optional[str] = None, password: Optional[str] = None,
189
                 rdns: Optional[bool] = None): ...
190
    def connect(self, dest_host: str, dest_port: int,
191
                timeout: Optional[float] = None, **kwargs) -> socket.socket: ...
192
```
193

194
[V2 Enhanced API](./v2-api.md)