0
# httplib2
1

2
A comprehensive HTTP client library for Python that supports many features left out of other HTTP libraries. httplib2 provides HTTP and HTTPS support with SSL verification, HTTP 1.1 Keep-Alive connections, multiple authentication methods (Digest, Basic, and WSSE), intelligent caching with Cache-Control support, all HTTP request methods, automatic redirects, compression handling, and lost update protection.
3

4
## Package Information
5

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

10
## Core Imports
11

12
```python
13
import httplib2
14
```
15

16
## Basic Usage
17

18
```python
19
import httplib2
20

21
# Create an Http client with caching
22
h = httplib2.Http(".cache")
23

24
# Simple GET request
25
(resp, content) = h.request("http://example.org/", "GET")
26
print(resp.status)
27
print(content)
28

29
# POST request with data
30
body = "This is request body data"
31
headers = {'content-type': 'text/plain'}
32
(resp, content) = h.request("https://example.org/api", "POST", 
33
                           body=body, headers=headers)
34

35
# Add authentication credentials
36
h.add_credentials('username', 'password')
37
(resp, content) = h.request("https://example.org/protected", "GET")
38
```
39

40
## Architecture
41

42
httplib2 is built around several key components:
43

44
- **Http**: Main client class managing connections, caching, and authentication
45
- **Response**: Dictionary-like response object containing status and headers  
46
- **Authentication**: Pluggable authentication system supporting multiple auth methods
47
- **Caching**: Built-in HTTP caching with Cache-Control header support
48
- **Connection Management**: Persistent connections with timeout and proxy support
49

50
## Capabilities
51

52
### HTTP Client
53

54
Core HTTP client functionality providing request/response handling, connection management, caching, and authentication. The main Http class serves as the primary interface for all HTTP operations.
55

56
```python { .api }
57
class Http:
58
    def __init__(self, cache=None, timeout=None, proxy_info=None, 
59
                 ca_certs=None, disable_ssl_certificate_validation=False,
60
                 tls_maximum_version=None, tls_minimum_version=None):
61
        """HTTP client with caching and authentication support."""
62
    
63
    def request(self, uri, method="GET", body=None, headers=None, 
64
                redirections=5, connection_type=None):
65
        """
66
        Perform HTTP request.
67
        
68
        Args:
69
            uri (str): Absolute URI for the request
70
            method (str): HTTP method (GET, POST, PUT, DELETE, etc.)
71
            body (str): Request body data
72
            headers (dict): HTTP headers
73
            redirections (int): Maximum redirects to follow
74
            connection_type: Connection class to use
75
            
76
        Returns:
77
            tuple: (Response, content) where Response is headers/status
78
                   and content is response body bytes
79
        """
80
    
81
    def add_credentials(self, name, password, domain=""):
82
        """Add username/password for authentication."""
83
    
84
    def add_certificate(self, key, cert, domain, password=None):
85
        """Add client certificate for authentication."""
86
    
87
    def clear_credentials(self):
88
        """Remove all stored credentials."""
89
```
90

91
[HTTP Client](./http-client.md)
92

93
### Response Handling
94

95
Response objects provide access to HTTP status codes, headers, and response metadata. Response objects behave like dictionaries for header access while providing additional status information.
96

97
```python { .api }
98
class Response(dict):
99
    """HTTP response containing status and headers."""
100
    
101
    def __init__(self, info):
102
        """Initialize from HTTP response info."""
103
    
104
    # Dictionary interface for headers
105
    # Additional attributes: status, reason, version
106
```
107

108
[Response Handling](./response-handling.md)
109

110
### Authentication
111

112
Multiple authentication methods including Basic, Digest, WSSE, HMAC Digest, and Google Login authentication. Authentication is handled automatically once credentials are configured.
113

114
```python { .api }
115
class Authentication:
116
    """Base authentication class."""
117
    
118
    def request(self, method, request_uri, headers, content):
119
        """Modify request headers for authentication."""
120
    
121
    def response(self, response, content):
122
        """Process authentication response."""
123

124
class BasicAuthentication(Authentication):
125
    """HTTP Basic authentication."""
126

127
class DigestAuthentication(Authentication):
128
    """HTTP Digest authentication."""
129

130
class WsseAuthentication(Authentication):
131
    """WSSE authentication."""
132
```
133

134
[Authentication](./authentication.md)
135

136
### Caching
137

138
File-based HTTP caching with Cache-Control header support, ETag validation, and Last-Modified handling. Caching improves performance by storing responses locally and respecting HTTP cache semantics.
139

140
```python { .api }
141
class FileCache:
142
    def __init__(self, cache, safe=None):
143
        """
144
        File-based cache implementation.
145
        
146
        Args:
147
            cache (str): Cache directory path
148
            safe (callable): Function to generate safe filenames
149
        """
150
    
151
    def get(self, key):
152
        """Retrieve cached content."""
153
    
154
    def set(self, key, value):
155
        """Store content in cache."""
156
    
157
    def delete(self, key):
158
        """Remove cached content."""
159
```
160

161
[Caching](./caching.md)
162

163
### Proxy Support
164

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

167
```python { .api }
168
class ProxyInfo:
169
    def __init__(self, proxy_type, proxy_host, proxy_port, 
170
                 proxy_rdns=True, proxy_user=None, proxy_pass=None,
171
                 proxy_headers=None):
172
        """
173
        Proxy configuration.
174
        
175
        Args:
176
            proxy_type: Type of proxy (socks.PROXY_TYPE_*)
177
            proxy_host (str): Proxy hostname
178
            proxy_port (int): Proxy port
179
            proxy_rdns (bool): Use remote DNS resolution
180
            proxy_user (str): Proxy username
181
            proxy_pass (str): Proxy password
182
            proxy_headers (dict): Additional headers for proxy requests
183
        """
184
    
185
    def applies_to(self, hostname):
186
        """Check if proxy applies to hostname."""
187

188
def proxy_info_from_environment(method="http"):
189
    """Create ProxyInfo from environment variables."""
190

191
def proxy_info_from_url(url, method="http", noproxy=None):
192
    """Create ProxyInfo from URL."""
193
```
194

195
[Proxy Support](./proxy-support.md)
196

197
### Error Handling
198

199
Comprehensive exception hierarchy for handling HTTP errors, connection failures, authentication issues, and malformed responses. All exceptions derive from HttpLib2Error base class.
200

201
```python { .api }
202
class HttpLib2Error(Exception):
203
    """Base exception for all httplib2 errors."""
204

205
class HttpLib2ErrorWithResponse(HttpLib2Error):
206
    """Exception that includes response data."""
207
    
208
    def __init__(self, desc, response, content):
209
        self.response = response
210
        self.content = content
211

212
class RedirectLimit(HttpLib2ErrorWithResponse):
213
    """Too many redirects followed."""
214

215
class RedirectMissingLocation(HttpLib2ErrorWithResponse):
216
    """Redirect without Location header."""
217

218
class FailedToDecompressContent(HttpLib2ErrorWithResponse):
219
    """Content decompression failure."""
220
```
221

222
[Error Handling](./error-handling.md)
223

224
### Utilities
225

226
URI parsing, normalization, IRI to URI conversion, certificate management, and other utility functions supporting the main HTTP client functionality.
227

228
```python { .api }
229
def parse_uri(uri):
230
    """Parse URI into components."""
231

232
def urlnorm(uri):
233
    """Normalize URI format."""
234

235
def iri2uri(uri):
236
    """Convert IRI to URI."""
237

238
def has_timeout(timeout):
239
    """Check if timeout is set."""
240
```
241

242
[Utilities](./utilities.md)
243

244
## Constants
245

246
```python { .api }
247
__version__ = "0.30.0"
248
debuglevel = 0  # HTTP debug level
249
RETRIES = 2  # Connection retry attempts
250
DEFAULT_MAX_REDIRECTS = 5  # Maximum redirects
251
SAFE_METHODS = ("GET", "HEAD", "OPTIONS", "TRACE")
252
REDIRECT_CODES = frozenset((300, 301, 302, 303, 307, 308))
253
```