0
# requests-toolbelt
1

2
A utility belt for advanced users of python-requests. This package provides a comprehensive collection of specialized tools and enhancements that extend the core functionality of HTTP requests, including streaming multipart encoding, SSL adapters, authentication utilities, cookie management, download tools, and parallel request execution.
3

4
## Package Information
5

6
- **Package Name**: requests-toolbelt
7
- **Language**: Python
8
- **Installation**: `pip install requests-toolbelt`
9
- **Requirements**: Python 2.7, 3.4+; requests>=2.0.1,<3.0.0
10

11
## Core Imports
12

13
```python
14
import requests_toolbelt
15
```
16

17
Common usage patterns:
18

19
```python
20
# Main exports - available directly from requests_toolbelt
21
from requests_toolbelt import (
22
    MultipartEncoder, MultipartEncoderMonitor, MultipartDecoder,
23
    GuessAuth, SSLAdapter, SourceAddressAdapter, StreamingIterator, user_agent,
24
    ImproperBodyPartContentException, NonMultipartContentTypeException
25
)
26

27
# Specific sub-module imports
28
from requests_toolbelt.auth.guess import GuessProxyAuth
29
from requests_toolbelt.adapters.x509 import X509Adapter
30
from requests_toolbelt.utils.dump import dump_response
31
from requests_toolbelt.sessions import BaseUrlSession
32
from requests_toolbelt import threaded
33
```
34

35
## Basic Usage
36

37
```python
38
import requests
39
from requests_toolbelt import MultipartEncoder
40

41
# Streaming multipart form uploads
42
encoder = MultipartEncoder({
43
    'field': 'value',
44
    'file': ('filename.txt', open('file.txt', 'rb'), 'text/plain')
45
})
46

47
response = requests.post(
48
    'https://httpbin.org/post',
49
    data=encoder,
50
    headers={'Content-Type': encoder.content_type}
51
)
52

53
# Automatic authentication detection
54
from requests_toolbelt import GuessAuth
55

56
response = requests.get(
57
    'https://httpbin.org/basic-auth/user/pass',
58
    auth=GuessAuth('user', 'pass')
59
)
60

61
# Debug request/response details
62
from requests_toolbelt.utils import dump_response
63
print(dump_response(response).decode('utf-8'))
64
```
65

66
## Architecture
67

68
The requests-toolbelt library extends the requests ecosystem through several key architectural components:
69

70
- **Adapters**: HTTPAdapter subclasses that modify connection behavior (SSL protocols, source addressing, certificates)
71
- **Authentication**: Pluggable auth handlers that integrate with requests' auth system
72
- **Multipart Processing**: Streaming encoders/decoders for efficient handling of large multipart content
73
- **Utilities**: Helper functions for debugging, user-agent construction, and URL encoding
74
- **Threading**: Thread pool implementation for concurrent request execution
75
- **Sessions**: Enhanced session classes with additional capabilities
76

77
This modular design allows developers to selectively use only the components they need while maintaining full compatibility with the standard requests library.
78

79
## Capabilities
80

81
### Multipart Encoding and Decoding
82

83
Streaming multipart/form-data encoder for efficient file uploads and form submissions, plus decoder for parsing multipart responses. Includes progress monitoring and supports large files without loading everything into memory.
84

85
```python { .api }
86
class MultipartEncoder:
87
    def __init__(self, fields, boundary=None, encoding='utf-8'): ...
88
    @property
89
    def content_type(self) -> str: ...
90

91
class MultipartEncoderMonitor:
92
    def __init__(self, encoder, callback): ...
93

94
class MultipartDecoder:
95
    def __init__(self, content, content_type): ...
96
```
97

98
[Multipart Processing](./multipart.md)
99

100
### Authentication
101

102
Automatic authentication detection and specialized authentication handlers including GuessAuth for detecting Basic/Digest auth and proxy authentication support.
103

104
```python { .api }
105
class GuessAuth:
106
    def __init__(self, username, password): ...
107
```
108

109
Note: GuessProxyAuth is available via `from requests_toolbelt.auth.guess import GuessProxyAuth`
110

111
[Authentication](./authentication.md)
112

113
### HTTP Adapters
114

115
Specialized HTTPAdapter implementations for SSL protocol selection, source address binding, certificate verification, and socket options configuration.
116

117
```python { .api }
118
class SSLAdapter: ...
119
class SourceAddressAdapter: ...
120
```
121

122
Note: X509Adapter, FingerprintAdapter, and others available via specific imports from `requests_toolbelt.adapters.*`
123

124
[HTTP Adapters](./adapters.md)
125

126
### Download Utilities
127

128
Tools for streaming downloads to files, monitoring download progress, and handling multiple download destinations simultaneously.
129

130
```python { .api }
131
def stream_response_to_file(response, path=None, chunksize=512): ...
132
def tee(response, fileobject, chunksize=512, decode_content=True): ...
133
def get_download_file_path(response, path): ...
134
```
135

136
[Download Utilities](./downloads.md)
137

138
### Parallel Requests
139

140
Thread pool implementation for executing multiple HTTP requests concurrently with session reuse and customizable initialization.
141

142
```python { .api }
143
def map(requests, **kwargs): ...
144

145
class Pool:
146
    def __init__(self, num_processes=None, initializer=None, initargs=None, job_queue=None): ...
147
```
148

149
[Parallel Requests](./threading.md)
150

151
### Debugging and Utilities
152

153
Request/response dumping for debugging, enhanced URL encoding, user-agent construction, and other utility functions.
154

155
```python { .api }
156
def dump_response(response, request_prefix=b'< ', response_prefix=b'> ', data_array=None): ...
157
def dump_all(response, request_prefix=b'< ', response_prefix=b'> '): ...
158
def user_agent(name, version, extras=None): ...
159
```
160

161
[Utilities](./utilities.md)
162

163
### Sessions and Streaming
164

165
Enhanced session classes with base URL support and streaming iterators for efficient handling of large uploads with known sizes.
166

167
```python { .api }
168
class BaseUrlSession:
169
    def __init__(self, base_url=None): ...
170

171
class StreamingIterator:
172
    def __init__(self, size, iterator): ...
173
```
174

175
[Sessions and Streaming](./sessions-streaming.md)
176

177
### Cookies and Exceptions
178

179
Specialized cookie jar implementations and custom exception classes for better error handling.
180

181
```python { .api }
182
class ForgetfulCookieJar: ...
183

184
class StreamingError(Exception): ...
185
class VersionMismatchError(Exception): ...
186
```
187

188
[Cookies and Exceptions](./cookies-exceptions.md)