0
# HTTP Request Methods
1

2
Core HTTP request functions supporting all standard methods with comprehensive parameter options for headers, authentication, cookies, timeouts, and data handling. All functions return Twisted Deferreds that fire with response objects.
3

4
## Capabilities
5

6
### GET Requests
7

8
Makes HTTP GET requests for retrieving data from servers.
9

10
```python { .api }
11
def get(url, headers=None, **kwargs):
12
    """
13
    Make a GET request.
14
    
15
    Parameters:
16
    - url: str, bytes, EncodedURL, or DecodedURL - Target URL
17
    - headers: Headers, dict, or None - HTTP headers to send
18
    - params: dict, list of tuples, or None - Query string parameters
19
    - auth: tuple of (username, password) or None - HTTP Basic Auth
20
    - cookies: CookieJar, dict, or None - Cookies to send
21
    - timeout: int or None - Request timeout in seconds
22
    - allow_redirects: bool - Follow redirects (default: True)
23
    - browser_like_redirects: bool - Use browser-like redirect behavior (default: False)
24
    - unbuffered: bool - Disable response buffering (default: False)
25
    - reactor: Twisted reactor or None - Custom reactor
26
    - persistent: bool - Use persistent connections (default: True)
27
    - agent: IAgent or None - Custom agent
28
    
29
    Returns:
30
    Deferred that fires with _Response object
31
    """
32
```
33

34
### POST Requests
35

36
Makes HTTP POST requests for sending data to servers.
37

38
```python { .api }
39
def post(url, data=None, **kwargs):
40
    """
41
    Make a POST request.
42
    
43
    Parameters:
44
    - url: str, bytes, EncodedURL, or DecodedURL - Target URL
45
    - data: bytes, file-like, dict, list, or None - Request body data
46
    - json: dict, list, or None - JSON data (mutually exclusive with data)
47
    - files: dict, list, or None - Files to upload (creates multipart request)
48
    - headers: Headers, dict, or None - HTTP headers to send
49
    - params: dict, list of tuples, or None - Query string parameters
50
    - auth: tuple of (username, password) or None - HTTP Basic Auth
51
    - cookies: CookieJar, dict, or None - Cookies to send
52
    - timeout: int or None - Request timeout in seconds
53
    - allow_redirects: bool - Follow redirects (default: True)
54
    - browser_like_redirects: bool - Use browser-like redirect behavior (default: False)
55
    - unbuffered: bool - Disable response buffering (default: False)
56
    - reactor: Twisted reactor or None - Custom reactor
57
    - persistent: bool - Use persistent connections (default: True)
58
    - agent: IAgent or None - Custom agent
59
    
60
    Returns:
61
    Deferred that fires with _Response object
62
    """
63
```
64

65
### PUT Requests
66

67
Makes HTTP PUT requests for creating or updating resources.
68

69
```python { .api }
70
def put(url, data=None, **kwargs):
71
    """
72
    Make a PUT request.
73
    
74
    Parameters:
75
    - url: str, bytes, EncodedURL, or DecodedURL - Target URL
76
    - data: bytes, file-like, dict, list, or None - Request body data
77
    - json: dict, list, or None - JSON data (mutually exclusive with data)
78
    - files: dict, list, or None - Files to upload (creates multipart request)
79
    - headers: Headers, dict, or None - HTTP headers to send
80
    - params: dict, list of tuples, or None - Query string parameters
81
    - auth: tuple of (username, password) or None - HTTP Basic Auth
82
    - cookies: CookieJar, dict, or None - Cookies to send
83
    - timeout: int or None - Request timeout in seconds
84
    - allow_redirects: bool - Follow redirects (default: True)
85
    - browser_like_redirects: bool - Use browser-like redirect behavior (default: False)
86
    - unbuffered: bool - Disable response buffering (default: False)
87
    - reactor: Twisted reactor or None - Custom reactor
88
    - persistent: bool - Use persistent connections (default: True)
89
    - agent: IAgent or None - Custom agent
90
    
91
    Returns:
92
    Deferred that fires with _Response object
93
    """
94
```
95

96
### PATCH Requests
97

98
Makes HTTP PATCH requests for partial resource updates.
99

100
```python { .api }
101
def patch(url, data=None, **kwargs):
102
    """
103
    Make a PATCH request.
104
    
105
    Parameters:
106
    - url: str, bytes, EncodedURL, or DecodedURL - Target URL
107
    - data: bytes, file-like, dict, list, or None - Request body data
108
    - json: dict, list, or None - JSON data (mutually exclusive with data)
109
    - files: dict, list, or None - Files to upload (creates multipart request)
110
    - headers: Headers, dict, or None - HTTP headers to send
111
    - params: dict, list of tuples, or None - Query string parameters
112
    - auth: tuple of (username, password) or None - HTTP Basic Auth
113
    - cookies: CookieJar, dict, or None - Cookies to send
114
    - timeout: int or None - Request timeout in seconds
115
    - allow_redirects: bool - Follow redirects (default: True)
116
    - browser_like_redirects: bool - Use browser-like redirect behavior (default: False)
117
    - unbuffered: bool - Disable response buffering (default: False)
118
    - reactor: Twisted reactor or None - Custom reactor
119
    - persistent: bool - Use persistent connections (default: True)
120
    - agent: IAgent or None - Custom agent
121
    
122
    Returns:
123
    Deferred that fires with _Response object
124
    """
125
```
126

127
### DELETE Requests
128

129
Makes HTTP DELETE requests for removing resources.
130

131
```python { .api }
132
def delete(url, **kwargs):
133
    """
134
    Make a DELETE request.
135
    
136
    Parameters:
137
    - url: str, bytes, EncodedURL, or DecodedURL - Target URL
138
    - headers: Headers, dict, or None - HTTP headers to send
139
    - params: dict, list of tuples, or None - Query string parameters
140
    - auth: tuple of (username, password) or None - HTTP Basic Auth
141
    - cookies: CookieJar, dict, or None - Cookies to send
142
    - timeout: int or None - Request timeout in seconds
143
    - allow_redirects: bool - Follow redirects (default: True)
144
    - browser_like_redirects: bool - Use browser-like redirect behavior (default: False)
145
    - unbuffered: bool - Disable response buffering (default: False)
146
    - reactor: Twisted reactor or None - Custom reactor
147
    - persistent: bool - Use persistent connections (default: True)
148
    - agent: IAgent or None - Custom agent
149
    
150
    Returns:
151
    Deferred that fires with _Response object
152
    """
153
```
154

155
### HEAD Requests
156

157
Makes HTTP HEAD requests for retrieving headers without response body.
158

159
```python { .api }
160
def head(url, **kwargs):
161
    """
162
    Make a HEAD request.
163
    
164
    Parameters:
165
    - url: str, bytes, EncodedURL, or DecodedURL - Target URL
166
    - headers: Headers, dict, or None - HTTP headers to send
167
    - params: dict, list of tuples, or None - Query string parameters
168
    - auth: tuple of (username, password) or None - HTTP Basic Auth
169
    - cookies: CookieJar, dict, or None - Cookies to send
170
    - timeout: int or None - Request timeout in seconds
171
    - allow_redirects: bool - Follow redirects (default: True)
172
    - browser_like_redirects: bool - Use browser-like redirect behavior (default: False)
173
    - unbuffered: bool - Disable response buffering (default: False)
174
    - reactor: Twisted reactor or None - Custom reactor
175
    - persistent: bool - Use persistent connections (default: True)
176
    - agent: IAgent or None - Custom agent
177
    
178
    Returns:
179
    Deferred that fires with _Response object
180
    """
181
```
182

183
### Generic Requests
184

185
Makes HTTP requests with any method.
186

187
```python { .api }
188
def request(method, url, **kwargs):
189
    """
190
    Make an HTTP request with any method.
191
    
192
    Parameters:
193
    - method: str - HTTP method ('GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', etc.)
194
    - url: str, bytes, EncodedURL, or DecodedURL - Target URL
195
    - headers: Headers, dict, or None - HTTP headers to send
196
    - params: dict, list of tuples, or None - Query string parameters
197
    - data: bytes, file-like, dict, list, or None - Request body data
198
    - json: dict, list, or None - JSON data (mutually exclusive with data)
199
    - files: dict, list, or None - Files to upload (creates multipart request)
200
    - auth: tuple of (username, password) or None - HTTP Basic Auth
201
    - cookies: CookieJar, dict, or None - Cookies to send
202
    - timeout: int or None - Request timeout in seconds
203
    - allow_redirects: bool - Follow redirects (default: True)
204
    - browser_like_redirects: bool - Use browser-like redirect behavior (default: False)
205
    - unbuffered: bool - Disable response buffering (default: False)
206
    - reactor: Twisted reactor or None - Custom reactor
207
    - persistent: bool - Use persistent connections (default: True)
208
    - agent: IAgent or None - Custom agent
209
    
210
    Returns:
211
    Deferred that fires with _Response object
212
    """
213
```
214

215
## Usage Examples
216

217
### Basic Requests
218

219
```python
220
import treq
221
from twisted.internet import defer
222

223
@defer.inlineCallbacks
224
def make_requests():
225
    # Simple GET
226
    response = yield treq.get('https://httpbin.org/get')
227
    
228
    # GET with query parameters
229
    response = yield treq.get('https://httpbin.org/get', params={'key': 'value'})
230
    
231
    # POST with form data
232
    response = yield treq.post('https://httpbin.org/post', data={'field': 'value'})
233
    
234
    # POST with JSON
235
    response = yield treq.post('https://httpbin.org/post', json={'key': 'value'})
236
```
237

238
### File Uploads
239

240
```python
241
@defer.inlineCallbacks
242
def upload_file():
243
    # Upload a single file
244
    with open('document.pdf', 'rb') as f:
245
        response = yield treq.post(
246
            'https://httpbin.org/post',
247
            files={'file': f}
248
        )
249
    
250
    # Upload with additional form data
251
    with open('image.jpg', 'rb') as f:
252
        response = yield treq.post(
253
            'https://httpbin.org/post',
254
            data={'title': 'My Upload'},
255
            files={'image': f}
256
        )
257
    
258
    # Upload with custom filename and content type
259
    with open('data.txt', 'rb') as f:
260
        response = yield treq.post(
261
            'https://httpbin.org/post',
262
            files={'data': ('custom_name.txt', 'text/plain', f)}
263
        )
264
```
265

266
### Authentication and Headers
267

268
```python
269
@defer.inlineCallbacks
270
def authenticated_requests():
271
    # Basic authentication
272
    response = yield treq.get(
273
        'https://httpbin.org/basic-auth/user/pass',
274
        auth=('user', 'pass')
275
    )
276
    
277
    # Custom headers
278
    response = yield treq.get(
279
        'https://httpbin.org/get',
280
        headers={'User-Agent': 'My App 1.0', 'Accept': 'application/json'}
281
    )
282
    
283
    # Cookies
284
    response = yield treq.get(
285
        'https://httpbin.org/cookies',
286
        cookies={'session': 'abc123', 'preference': 'dark'}
287
    )
288
```
289

290
## Types
291

292
Request parameter types:
293

294
```python { .api }
295
# URL parameter types
296
_URLType = Union[str, bytes, EncodedURL, DecodedURL]
297

298
# Query parameters
299
_ParamsType = Union[
300
    Mapping[str, Union[str, Tuple[str, ...], List[str]]],
301
    List[Tuple[str, str]]
302
]
303

304
# Request body data
305
_DataType = Union[
306
    bytes,                              # Raw bytes
307
    io.BytesIO,                         # Byte stream
308
    io.BufferedReader,                  # File object
309
    IBodyProducer,                      # Twisted body producer
310
    Dict[str, str],                     # Form data
311
    List[Tuple[str, str]]               # Form tuples
312
]
313

314
# File upload types
315
_FileValue = Union[
316
    str,                                # Simple string content
317
    bytes,                              # Byte content
318
    Tuple[str, str, IBodyProducer]      # (filename, content_type, producer)
319
]
320

321
_FilesType = Union[
322
    Mapping[str, _FileValue],           # Dict mapping field names to files
323
    Iterable[Tuple[str, _FileValue]]    # List of (field_name, file) tuples
324
]
325

326
# JSON data
327
_JSONType = Any  # Any JSON-serializable Python object
328
```