0
# urllib Integration (sockshandler)
1

2
HTTP and HTTPS request handling through SOCKS proxies using urllib2 and urllib.request. This module provides handler classes that integrate with Python's urllib system to route web requests through SOCKS proxies.
3

4
## Capabilities
5

6
### HTTP Handler
7

8
Creates urllib2/urllib.request handlers for making HTTP and HTTPS requests through SOCKS proxies, with automatic fallback handling for SOCKS4 servers that don't support remote DNS resolution.
9

10
```python { .api }
11
class SocksiPyHandler:
12
    """urllib2/urllib.request handler for SOCKS proxies."""
13
    
14
    def __init__(self, proxytype: int, proxyaddr: str, proxyport: int = None, rdns: bool = True, username: str = None, password: str = None, **kwargs):
15
        """
16
        Initialize SOCKS proxy handler.
17
        
18
        Parameters:
19
        - proxytype: socks.SOCKS4, socks.SOCKS5, or socks.HTTP
20
        - proxyaddr: proxy server hostname or IP address
21
        - proxyport: proxy server port (defaults: 1080 for SOCKS, 8080 for HTTP)
22
        - rdns: whether to resolve DNS remotely (True) or locally (False)
23
        - username: proxy authentication username (SOCKS5 and SOCKS4 userid)
24
        - password: proxy authentication password (SOCKS5 only)
25
        - **kwargs: additional arguments passed to connection classes
26
        """
27
    
28
    def http_open(self, req) -> urllib2.HTTPResponse:
29
        """Handle HTTP requests through the SOCKS proxy."""
30
    
31
    def https_open(self, req) -> urllib2.HTTPResponse:
32
        """Handle HTTPS requests through the SOCKS proxy."""
33
```
34

35
### Connection Classes
36

37
Low-level HTTP and HTTPS connection classes that handle the actual proxy tunneling for urllib2/urllib.request handlers.
38

39
```python { .api }
40
class SocksiPyConnection:
41
    """HTTP connection through SOCKS proxy."""
42
    
43
    def __init__(self, proxytype: int, proxyaddr: str, proxyport: int = None, rdns: bool = True, username: str = None, password: str = None, *args, **kwargs):
44
        """Initialize HTTP connection with proxy settings."""
45
    
46
    def connect(self):
47
        """Establish HTTP connection through SOCKS proxy."""
48

49
class SocksiPyConnectionS:
50
    """HTTPS connection through SOCKS proxy."""
51
    
52
    def __init__(self, proxytype: int, proxyaddr: str, proxyport: int = None, rdns: bool = True, username: str = None, password: str = None, *args, **kwargs):
53
        """Initialize HTTPS connection with proxy settings."""
54
    
55
    def connect(self):
56
        """Establish HTTPS connection through SOCKS proxy with SSL wrapping."""
57
```
58

59
### Utility Functions
60

61
Helper functions for IP address validation and dictionary merging used internally by the connection classes.
62

63
```python { .api }
64
def is_ip(s: str) -> bool:
65
    """
66
    Check if string is a valid IPv4 or IPv6 address.
67
    
68
    Parameters:
69
    - s: string to check
70
    
71
    Returns:
72
    bool: True if valid IP address, False otherwise
73
    """
74

75
def merge_dict(a: dict, b: dict) -> dict:
76
    """
77
    Merge two dictionaries, with values from b taking precedence.
78
    
79
    Parameters:
80
    - a: base dictionary
81
    - b: dictionary with override values
82
    
83
    Returns:
84
    dict: merged dictionary
85
    """
86
```
87

88
## Usage Examples
89

90
### Basic urllib2/urllib.request Integration
91

92
```python
93
import urllib2
94
import socks
95
import sockshandler
96

97
# Create SOCKS5 proxy handler
98
handler = sockshandler.SocksiPyHandler(
99
    socks.SOCKS5, 
100
    "localhost", 
101
    9050,
102
    username="user",
103
    password="pass"
104
)
105

106
# Build opener with the handler
107
opener = urllib2.build_opener(handler)
108

109
# Make requests through the proxy
110
response = opener.open("http://httpbin.org/ip")
111
print(response.read().decode())
112

113
response = opener.open("https://httpbin.org/ip")
114
print(response.read().decode())
115
```
116

117
### Python 3 urllib.request Integration
118

119
```python
120
import urllib.request
121
import socks
122
import sockshandler
123

124
# Create SOCKS5 proxy handler  
125
handler = sockshandler.SocksiPyHandler(socks.SOCKS5, "localhost", 9050)
126

127
# Build opener
128
opener = urllib.request.build_opener(handler)
129

130
# Install as global default (optional)
131
urllib.request.install_opener(opener)
132

133
# Make requests
134
with urllib.request.urlopen("http://example.com") as response:
135
    content = response.read()
136
```
137

138
### SOCKS4 with Automatic Fallback
139

140
```python
141
import urllib2
142
import socks
143
import sockshandler
144

145
# Handler automatically handles SOCKS4 servers that don't support remote DNS
146
handler = sockshandler.SocksiPyHandler(
147
    socks.SOCKS4,
148
    "socks4-proxy.example.com",
149
    1080,
150
    rdns=True  # Will fallback to local DNS if server doesn't support remote
151
)
152

153
opener = urllib2.build_opener(handler)
154
response = opener.open("http://example.com")
155
```
156

157
## Error Handling
158

159
The handler classes automatically handle common SOCKS4 compatibility issues:
160

161
- **SOCKS4 Remote DNS Fallback**: If a SOCKS4 server returns error 0x5b and remote DNS was requested, automatically retries with local DNS resolution
162
- **Proxy Error Propagation**: All SOCKS errors (SOCKS4Error, SOCKS5Error, etc.) are propagated up through urllib2's exception system
163
- **SSL Certificate Validation**: HTTPS connections properly validate SSL certificates and handle SSL errors
164

165
## Global State
166

167
```python { .api }
168
socks4_no_rdns: set[str]  # Set of SOCKS4 proxy addresses that don't support remote DNS
169
```
170

171
This global set tracks SOCKS4 proxy servers that have been determined not to support remote DNS resolution, enabling automatic fallback behavior for subsequent connections.