0
# Request and Response Objects
1

2
Core objects that represent HTTP requests and responses, providing full control over request preparation and response handling. These objects form the foundation of the requests library's functionality.
3

4
## Capabilities
5

6
### Request Class
7

8
User-created Request objects that represent HTTP requests before they are sent.
9

10
```python { .api }
11
class Request:
12
    """
13
    A user-created Request object.
14
    
15
    Used to prepare a PreparedRequest, which is sent to the server.
16
    """
17

18
    def __init__(self, method=None, url=None, headers=None, files=None, 
19
                 data=None, params=None, auth=None, cookies=None, 
20
                 hooks=None, json=None):
21
        """
22
        Initialize a Request object.
23
        
24
        Parameters:
25
        - method: HTTP method to use ('GET', 'POST', etc.)
26
        - url: URL to send the request to
27
        - headers: dict of headers to send
28
        - files: dict of {filename: fileobject} for multipart upload
29
        - data: request body data (dict, list of tuples, bytes, or file-like)
30
        - params: URL parameters to append (dict or list of tuples)
31
        - auth: authentication tuple or handler
32
        - cookies: cookies to send (dict or CookieJar)
33
        - hooks: event hooks dict
34
        - json: JSON serializable object for request body
35
        """
36

37
    def prepare(self) -> 'PreparedRequest':
38
        """
39
        Prepare the request for sending.
40
        
41
        Returns:
42
        PreparedRequest object ready to send
43
        """
44
```
45

46
### PreparedRequest Class
47

48
Fully prepared request objects containing the exact bytes that will be sent to the server.
49

50
```python { .api }
51
class PreparedRequest:
52
    """
53
    The fully mutable PreparedRequest object.
54
    
55
    Contains the exact bytes that will be sent to the server.
56
    Should not be instantiated manually.
57
    
58
    Attributes:
59
    - method: HTTP method (str)
60
    - url: Full URL (str)
61
    - headers: Request headers (CaseInsensitiveDict)
62
    - body: Request body (bytes or str or None)
63
    - hooks: Event hooks (dict)
64
    - _cookies: CookieJar for cookie header generation
65
    - _body_position: Position marker for rewindable request bodies
66
    """
67

68
    def __init__(self):
69
        """Initialize a PreparedRequest object."""
70

71
    def prepare(self, method=None, url=None, files=None, data=None, 
72
                headers=None, params=None, auth=None, cookies=None, 
73
                hooks=None, json=None):
74
        """
75
        Prepare all aspects of the request.
76
        
77
        Parameters: Same as Request.__init__
78
        """
79

80
    def prepare_method(self, method: str):
81
        """Prepare the HTTP method."""
82

83
    def prepare_url(self, url: str, params):
84
        """Prepare the URL with parameters."""
85

86
    def prepare_headers(self, headers):
87
        """Prepare the headers."""
88

89
    def prepare_cookies(self, cookies):
90
        """Prepare the cookies."""
91

92
    def prepare_body(self, data, files, json=None):
93
        """Prepare the request body."""
94

95
    def prepare_auth(self, auth, url=''):
96
        """Prepare authentication."""
97

98
    def prepare_content_length(self, body):
99
        """Prepare Content-Length header."""
100

101
    def prepare_hooks(self, hooks):
102
        """Prepare event hooks."""
103

104
    def copy(self) -> 'PreparedRequest':
105
        """Create a copy of the PreparedRequest."""
106
```
107

108
### Response Class
109

110
Response objects containing server responses to HTTP requests.
111

112
```python { .api }
113
class Response:
114
    """
115
    The Response object contains a server's response to an HTTP request.
116
    """
117

118
    # Response attributes
119
    content: bytes  # Response content as bytes
120
    text: str  # Response content as text
121
    encoding: str  # Response encoding
122
    status_code: int  # HTTP status code
123
    headers: 'CaseInsensitiveDict'  # Response headers
124
    cookies: 'RequestsCookieJar'  # Response cookies
125
    url: str  # Final URL location of response
126
    history: list['Response']  # List of Response objects (redirects)
127
    reason: str  # Textual reason of response (e.g., 'OK', 'Not Found')
128
    request: 'PreparedRequest'  # PreparedRequest that generated this response
129
    elapsed: 'timedelta'  # Time elapsed between request and response
130
    raw: object  # Raw response object (urllib3.HTTPResponse)
131

132
    def __init__(self):
133
        """Initialize a Response object."""
134

135
    def __enter__(self):
136
        """Context manager entry."""
137

138
    def __exit__(self, *args):
139
        """Context manager exit."""
140

141
    def __bool__(self) -> bool:
142
        """Boolean evaluation based on status code."""
143

144
    def __nonzero__(self) -> bool:
145
        """Boolean evaluation for Python 2 compatibility."""
146

147
    def __iter__(self):
148
        """Iterate over response content in chunks."""
149

150
    @property
151
    def ok(self) -> bool:
152
        """True if status code is less than 400."""
153

154
    @property
155
    def is_redirect(self) -> bool:
156
        """True if response is a redirect."""
157

158
    @property
159
    def is_permanent_redirect(self) -> bool:
160
        """True if response is a permanent redirect."""
161

162
    @property
163
    def next(self):
164
        """Returns parsed header links if present."""
165

166
    @property
167
    def apparent_encoding(self) -> str:
168
        """Apparent encoding of response content."""
169

170
    def iter_content(self, chunk_size: int = 1, decode_unicode: bool = False):
171
        """
172
        Iterate over response data in chunks.
173
        
174
        Parameters:
175
        - chunk_size: Size of chunks to read
176
        - decode_unicode: Whether to decode content to unicode
177
        
178
        Yields:
179
        Chunks of response content
180
        """
181

182
    def iter_lines(self, chunk_size: int = 512, decode_unicode: bool = False, 
183
                   delimiter=None):
184
        """
185
        Iterate over response lines.
186
        
187
        Parameters:
188
        - chunk_size: Size of chunks to read
189
        - decode_unicode: Whether to decode content to unicode
190
        - delimiter: Line delimiter
191
        
192
        Yields:
193
        Lines from response content
194
        """
195

196
    def json(self, **kwargs) -> Union[dict, list]:
197
        """
198
        Parse response content as JSON.
199
        
200
        Parameters:
201
        - **kwargs: Arguments passed to json.loads()
202
        
203
        Returns:
204
        Parsed JSON data
205
        
206
        Raises:
207
        JSONDecodeError: If response is not valid JSON
208
        """
209

210
    @property
211
    def links(self) -> dict:
212
        """Returns parsed header links."""
213

214
    def raise_for_status(self):
215
        """
216
        Raise HTTPError for bad responses (4xx or 5xx status codes).
217
        
218
        Raises:
219
        HTTPError: If status code indicates an error
220
        """
221

222
    def close(self):
223
        """Release the connection back to the pool."""
224
```
225

226
## Usage Examples
227

228
### Basic Request Creation
229

230
```python
231
import requests
232

233
# Create a request object
234
req = requests.Request('GET', 'https://api.github.com/user', 
235
                      auth=('username', 'password'))
236

237
# Prepare the request
238
prepared = req.prepare()
239

240
# Send the prepared request
241
with requests.Session() as s:
242
    response = s.send(prepared)
243
    print(response.status_code)
244
```
245

246
### Working with Response Objects
247

248
```python
249
import requests
250

251
response = requests.get('https://api.github.com/users/octocat')
252

253
# Access response properties
254
print(f"Status: {response.status_code}")
255
print(f"Headers: {response.headers}")
256
print(f"URL: {response.url}")
257
print(f"Encoding: {response.encoding}")
258

259
# Check if request was successful
260
if response.ok:
261
    print("Request successful")
262

263
# Parse JSON response
264
try:
265
    data = response.json()
266
    print(f"User: {data['login']}")
267
except requests.exceptions.JSONDecodeError:
268
    print("Response is not valid JSON")
269

270
# Check for errors
271
try:
272
    response.raise_for_status()
273
except requests.exceptions.HTTPError as e:
274
    print(f"HTTP Error: {e}")
275
```
276

277
### Streaming Large Responses
278

279
```python
280
import requests
281

282
# Stream large file download
283
url = 'https://example.com/large-file.zip'
284
response = requests.get(url, stream=True)
285

286
with open('large-file.zip', 'wb') as f:
287
    for chunk in response.iter_content(chunk_size=8192):
288
        f.write(chunk)
289

290
# Stream and process lines
291
response = requests.get('https://example.com/large-text-file.txt', stream=True)
292
for line in response.iter_lines(decode_unicode=True):
293
    print(line)
294

295
response.close()  # Important to close streamed responses
296
```
297

298
### Response Context Manager
299

300
```python
301
import requests
302

303
# Use response as context manager for automatic cleanup
304
with requests.get('https://example.com/data.json', stream=True) as response:
305
    response.raise_for_status()
306
    data = response.json()
307
    # Process data...
308
# Response is automatically closed
309
```
310

311
### Advanced Request Preparation
312

313
```python
314
import requests
315

316
# Create and customize a request
317
req = requests.Request(
318
    method='POST',
319
    url='https://api.example.com/data',
320
    json={'key': 'value'},
321
    headers={'User-Agent': 'MyApp/1.0'},
322
    auth=('user', 'pass')
323
)
324

325
# Prepare and inspect before sending
326
prepared = req.prepare()
327
print(f"Method: {prepared.method}")
328
print(f"URL: {prepared.url}")
329
print(f"Headers: {prepared.headers}")
330
print(f"Body: {prepared.body}")
331

332
# Send the prepared request
333
with requests.Session() as s:
334
    response = s.send(prepared, timeout=30)
335
```
336

337
### Response History and Redirects
338

339
```python
340
import requests
341

342
response = requests.get('https://github.com')
343

344
# Check redirect history
345
if response.history:
346
    print("Request was redirected")
347
    for resp in response.history:
348
        print(f"Redirect from: {resp.url} -> {resp.status_code}")
349
    print(f"Final URL: {response.url}")
350

351
# Check redirect type
352
if response.is_redirect:
353
    print("Response is a redirect")
354
if response.is_permanent_redirect:
355
    print("Response is a permanent redirect")
356
```
357

358
## Constants
359

360
```python { .api }
361
# Redirect status codes
362
REDIRECT_STATI: tuple  # (301, 302, 303, 307, 308)
363

364
# Default limits
365
DEFAULT_REDIRECT_LIMIT: int  # 30
366
CONTENT_CHUNK_SIZE: int  # 10 * 1024
367
ITER_CHUNK_SIZE: int  # 512
368
```
369

370
## Request/Response Lifecycle
371

372
1. **Request Creation**: User creates a Request object with parameters
373
2. **Request Preparation**: Request is converted to PreparedRequest with exact bytes
374
3. **Request Sending**: PreparedRequest is sent via adapter (usually HTTPAdapter)
375
4. **Response Creation**: Server response is converted to Response object
376
5. **Response Processing**: User accesses response data, headers, status, etc.
377
6. **Cleanup**: Response connection is returned to pool or closed