0
# Proxy Support
1

2
Comprehensive proxy server support including HTTP, HTTPS, and SOCKS proxies with authentication and bypass configuration. Proxy settings can be configured manually or detected automatically from environment variables.
3

4
## Capabilities
5

6
### ProxyInfo Class
7

8
Configuration class for proxy server settings including authentication and bypass rules.
9

10
```python { .api }
11
class ProxyInfo:
12
    """Proxy configuration and management."""
13
    
14
    def __init__(self, proxy_type, proxy_host, proxy_port,
15
                 proxy_rdns=True, proxy_user=None, proxy_pass=None,
16
                 proxy_headers=None):
17
        """
18
        Initialize proxy configuration.
19
        
20
        Args:
21
            proxy_type: Proxy type (socks.PROXY_TYPE_HTTP, socks.PROXY_TYPE_SOCKS4, 
22
                       socks.PROXY_TYPE_SOCKS5)
23
            proxy_host (str): Proxy server hostname or IP
24
            proxy_port (int): Proxy server port number
25
            proxy_rdns (bool): Use remote DNS resolution (default True)
26
            proxy_user (str): Username for proxy authentication (optional)
27
            proxy_pass (str): Password for proxy authentication (optional)  
28
            proxy_headers (dict): Additional headers for proxy requests (optional)
29
        """
30
    
31
    def astuple(self):
32
        """
33
        Return proxy configuration as tuple.
34
        
35
        Returns:
36
            tuple: (proxy_type, proxy_host, proxy_port, proxy_rdns, 
37
                   proxy_user, proxy_pass, proxy_headers)
38
        """
39
    
40
    def isgood(self):
41
        """
42
        Check if proxy configuration is valid.
43
        
44
        Returns:
45
            bool: True if proxy can be used
46
        """
47
    
48
    def applies_to(self, hostname):
49
        """
50
        Check if proxy should be used for hostname.
51
        
52
        Args:
53
            hostname (str): Target hostname
54
            
55
        Returns:
56
            bool: True if proxy applies to this hostname
57
        """
58
    
59
    def bypass_host(self, hostname):
60
        """
61
        Check if hostname should bypass proxy.
62
        
63
        Args:
64
            hostname (str): Target hostname
65
            
66
        Returns:
67
            bool: True if hostname should bypass proxy
68
        """
69
```
70

71
### Proxy Utility Functions
72

73
Functions for creating proxy configurations from environment variables and URLs.
74

75
```python { .api }
76
def proxy_info_from_environment(method="http"):
77
    """
78
    Create ProxyInfo from environment variables.
79
    
80
    Checks environment variables in order:
81
    - <method>_proxy (e.g., http_proxy, https_proxy)
82
    - <METHOD>_PROXY (uppercase version)
83
    - no_proxy/NO_PROXY for bypass list
84
    
85
    Args:
86
        method (str): Protocol method ("http" or "https")
87
        
88
    Returns:
89
        ProxyInfo: Proxy configuration, or None if no proxy configured
90
    """
91

92
def proxy_info_from_url(url, method="http", noproxy=None):
93
    """
94
    Create ProxyInfo from proxy URL.
95
    
96
    Args:
97
        url (str): Proxy URL (e.g., "http://proxy.example.com:8080")
98
        method (str): Protocol method
99
        noproxy (str): Comma-separated list of hosts to bypass
100
        
101
    Returns:
102
        ProxyInfo: Proxy configuration
103
    """
104
```
105

106
### Proxy Types
107

108
httplib2 supports multiple proxy types through the PySocks library:
109

110
```python { .api }
111
# Import proxy types from socks module
112
import socks
113

114
# Available proxy types:
115
socks.PROXY_TYPE_HTTP     # HTTP proxy (most common)
116
socks.PROXY_TYPE_SOCKS4   # SOCKS4 proxy  
117
socks.PROXY_TYPE_SOCKS5   # SOCKS5 proxy (supports authentication)
118
```
119

120
### Usage Examples
121

122
#### Basic HTTP Proxy
123

124
```python
125
import httplib2
126
import socks
127

128
# Configure HTTP proxy
129
proxy_info = httplib2.ProxyInfo(
130
    socks.PROXY_TYPE_HTTP,
131
    'proxy.example.com',
132
    8080
133
)
134

135
h = httplib2.Http(proxy_info=proxy_info)
136
(resp, content) = h.request("http://example.org/")
137
```
138

139
#### Proxy with Authentication
140

141
```python
142
import httplib2
143
import socks
144

145
# HTTP proxy with username/password
146
proxy_info = httplib2.ProxyInfo(
147
    socks.PROXY_TYPE_HTTP,
148
    'proxy.example.com', 
149
    8080,
150
    proxy_user='proxyuser',
151
    proxy_pass='proxypass'
152
)
153

154
h = httplib2.Http(proxy_info=proxy_info)
155
(resp, content) = h.request("https://secure.example.com/")
156
```
157

158
#### SOCKS5 Proxy
159

160
```python
161
import httplib2
162
import socks
163

164
# SOCKS5 proxy configuration
165
proxy_info = httplib2.ProxyInfo(
166
    socks.PROXY_TYPE_SOCKS5,
167
    'socks.example.com',
168
    1080,
169
    proxy_user='sockuser',
170
    proxy_pass='sockpass'
171
)
172

173
h = httplib2.Http(proxy_info=proxy_info)
174
(resp, content) = h.request("http://example.org/")
175
```
176

177
#### Environment Variable Configuration
178

179
```python
180
import httplib2
181
import os
182

183
# Set environment variables
184
os.environ['http_proxy'] = 'http://proxy.example.com:8080'
185
os.environ['https_proxy'] = 'http://proxy.example.com:8080'
186
os.environ['no_proxy'] = 'localhost,127.0.0.1,.example.com'
187

188
# Create Http client that automatically uses environment proxy settings
189
h = httplib2.Http(proxy_info=httplib2.proxy_info_from_environment)
190

191
# Requests will use proxy based on environment variables
192
(resp, content) = h.request("http://external.com/")      # Uses proxy
193
(resp, content) = h.request("http://internal.example.com/")  # Bypasses proxy
194
```
195

196
#### Proxy Auto-Detection
197

198
```python
199
import httplib2
200

201
# Function-based proxy configuration
202
def get_proxy_info(method):
203
    """Dynamic proxy selection based on method."""
204
    if method == "https":
205
        return httplib2.ProxyInfo(
206
            httplib2.socks.PROXY_TYPE_HTTP,
207
            'https-proxy.example.com', 
208
            8443
209
        )
210
    else:
211
        return httplib2.ProxyInfo(
212
            httplib2.socks.PROXY_TYPE_HTTP,
213
            'http-proxy.example.com',
214
            8080
215
        )
216

217
h = httplib2.Http(proxy_info=get_proxy_info)
218
(resp, content) = h.request("http://example.org/")   # Uses HTTP proxy
219
(resp, content) = h.request("https://example.org/")  # Uses HTTPS proxy
220
```
221

222
#### Proxy from URL
223

224
```python
225
import httplib2
226

227
# Create proxy info from URL string
228
proxy_url = "http://user:pass@proxy.example.com:8080"
229
proxy_info = httplib2.proxy_info_from_url(proxy_url)
230

231
h = httplib2.Http(proxy_info=proxy_info)
232
(resp, content) = h.request("http://example.org/")
233
```
234

235
### Proxy Bypass
236

237
Configure hosts that should bypass the proxy:
238

239
#### Environment Variable Bypass
240

241
```python
242
import os
243
import httplib2
244

245
# Configure proxy bypass via environment
246
os.environ['http_proxy'] = 'http://proxy.example.com:8080'
247
os.environ['no_proxy'] = 'localhost,127.0.0.1,*.local,.internal.com'
248

249
h = httplib2.Http(proxy_info=httplib2.proxy_info_from_environment)
250

251
# These requests bypass the proxy:
252
(resp, content) = h.request("http://localhost/")
253
(resp, content) = h.request("http://server.local/")
254
(resp, content) = h.request("http://api.internal.com/")
255

256
# This request uses the proxy:
257
(resp, content) = h.request("http://external.com/")
258
```
259

260
#### Programmatic Bypass
261

262
```python
263
import httplib2
264
from httplib2 import AllHosts
265

266
# Create proxy with bypass configuration
267
class CustomProxyInfo(httplib2.ProxyInfo):
268
    def __init__(self, *args, **kwargs):
269
        super().__init__(*args, **kwargs)
270
        self.bypass_hosts = ['.internal.com', 'localhost']
271
    
272
    def bypass_host(self, hostname):
273
        hostname = '.' + hostname.lstrip('.')
274
        for bypass in self.bypass_hosts:
275
            if hostname.endswith(bypass):
276
                return True
277
        return False
278

279
proxy_info = CustomProxyInfo(
280
    httplib2.socks.PROXY_TYPE_HTTP,
281
    'proxy.example.com',
282
    8080
283
)
284

285
h = httplib2.Http(proxy_info=proxy_info)
286
```
287

288
### Proxy Headers
289

290
Add custom headers to proxy requests:
291

292
```python
293
import httplib2
294
import socks
295

296
# Proxy with custom headers
297
proxy_headers = {
298
    'User-Agent': 'MyApp/1.0',
299
    'X-Forwarded-For': '192.168.1.100'
300
}
301

302
proxy_info = httplib2.ProxyInfo(
303
    socks.PROXY_TYPE_HTTP,
304
    'proxy.example.com',
305
    8080,
306
    proxy_headers=proxy_headers
307
)
308

309
h = httplib2.Http(proxy_info=proxy_info)
310
(resp, content) = h.request("http://example.org/")
311
```
312

313
### HTTPS Through Proxy
314

315
HTTPS requests through HTTP proxies use the CONNECT method:
316

317
```python
318
import httplib2
319
import socks
320

321
# HTTP proxy for HTTPS requests
322
proxy_info = httplib2.ProxyInfo(
323
    socks.PROXY_TYPE_HTTP,
324
    'proxy.example.com',
325
    8080,
326
    proxy_user='user',
327
    proxy_pass='pass'
328
)
329

330
h = httplib2.Http(proxy_info=proxy_info)
331

332
# HTTPS request tunneled through HTTP proxy
333
(resp, content) = h.request("https://secure.example.com/api")
334
```
335

336
### Error Handling
337

338
```python
339
import httplib2
340

341
try:
342
    proxy_info = httplib2.ProxyInfo(
343
        httplib2.socks.PROXY_TYPE_HTTP,
344
        'nonexistent-proxy.example.com',
345
        8080
346
    )
347
    
348
    h = httplib2.Http(proxy_info=proxy_info)
349
    (resp, content) = h.request("http://example.org/")
350
    
351
except httplib2.ProxiesUnavailableError:
352
    print("Proxy support not available (PySocks not installed)")
353
except httplib2.ServerNotFoundError:
354
    print("Proxy server not found")
355
except Exception as e:
356
    print(f"Proxy error: {e}")
357
```
358

359
### Performance Considerations
360

361
#### Connection Pooling
362
- Proxy connections are pooled separately from direct connections
363
- Connection key includes proxy information
364
- Reuses proxy connections when possible
365

366
#### DNS Resolution
367
- `proxy_rdns=True`: DNS resolution through proxy (default)
368
- `proxy_rdns=False`: Local DNS resolution
369
- SOCKS proxies support remote DNS resolution
370

371
#### Authentication Caching
372
- Proxy authentication credentials cached per proxy
373
- Reduces authentication overhead
374
- Automatically retries with credentials on 407 Proxy Authentication Required
375

376
### Proxy Configuration Patterns
377

378
#### Corporate Environment
379

380
```python
381
import httplib2
382
import os
383

384
# Typical corporate proxy setup
385
os.environ.update({
386
    'http_proxy': 'http://corporate-proxy.company.com:8080',
387
    'https_proxy': 'http://corporate-proxy.company.com:8080',
388
    'no_proxy': 'localhost,127.0.0.1,*.company.com,10.*,192.168.*'
389
})
390

391
h = httplib2.Http(proxy_info=httplib2.proxy_info_from_environment)
392
```
393

394
#### Development Environment
395

396
```python
397
import httplib2
398

399
# Development proxy for debugging
400
proxy_info = httplib2.ProxyInfo(
401
    httplib2.socks.PROXY_TYPE_HTTP,
402
    '127.0.0.1',  # Local proxy like Charles or Fiddler
403
    8888
404
)
405

406
h = httplib2.Http(proxy_info=proxy_info)
407
```
408

409
#### Load Balancing Proxies
410

411
```python
412
import httplib2
413
import random
414

415
# Multiple proxy servers for load balancing
416
proxy_servers = [
417
    ('proxy1.example.com', 8080),
418
    ('proxy2.example.com', 8080),
419
    ('proxy3.example.com', 8080)
420
]
421

422
def get_random_proxy(method):
423
    host, port = random.choice(proxy_servers)
424
    return httplib2.ProxyInfo(
425
        httplib2.socks.PROXY_TYPE_HTTP,
426
        host, port
427
    )
428

429
h = httplib2.Http(proxy_info=get_random_proxy)
430
```