0
# Request Functions API
1

2
Top-level convenience functions for making HTTP requests without explicitly managing a client instance. These functions are ideal for single requests or simple scripts.
3

4
## Overview
5

6
Each function creates a temporary client, makes the request, and automatically closes the connection. For multiple requests, consider using `httpx.Client` for better performance through connection reuse.
7

8
## Capabilities
9

10
### HTTP Method Functions
11

12
#### GET Request
13

14
```python { .api }
15
def get(url, *, params=None, headers=None, cookies=None, auth=None, proxy=None, follow_redirects=False, timeout=DEFAULT_TIMEOUT_CONFIG, verify=True, trust_env=True):
16
    """
17
    Send a GET request.
18
    
19
    Args:
20
        url (str): URL for the request
21
        params (dict, optional): Query parameters to append to URL
22
        headers (dict, optional): HTTP headers to send
23
        cookies (dict, optional): Cookies to send with request
24
        auth (Auth, optional): Authentication handler
25
        proxy (Proxy | str, optional): Proxy configuration
26
        follow_redirects (bool): Whether to follow HTTP redirects (default: False)
27
        timeout (Timeout): Request timeout configuration (default: 5.0s)
28
        verify (bool | str | SSLContext): SSL certificate verification (default: True)
29
        trust_env (bool): Use environment variables for proxy/SSL config (default: True)
30
    
31
    Returns:
32
        Response: HTTP response object
33
    
34
    Raises:
35
        RequestError: If the request fails
36
        HTTPStatusError: If response has 4xx/5xx status and raise_for_status() called
37
    """
38
```
39

40
#### POST Request
41

42
```python { .api }
43
def post(url, *, content=None, data=None, files=None, json=None, params=None, headers=None, cookies=None, auth=None, proxy=None, follow_redirects=False, timeout=DEFAULT_TIMEOUT_CONFIG, verify=True, trust_env=True):
44
    """
45
    Send a POST request.
46
    
47
    Args:
48
        url (str): URL for the request
49
        content (bytes, optional): Raw bytes content for request body
50
        data (dict, optional): Form data to send in request body
51
        files (dict, optional): Files to upload
52
        json (any, optional): JSON-serializable object for request body
53
        params (dict, optional): Query parameters to append to URL
54
        headers (dict, optional): HTTP headers to send
55
        cookies (dict, optional): Cookies to send with request
56
        auth (Auth, optional): Authentication handler
57
        proxy (Proxy | str, optional): Proxy configuration
58
        follow_redirects (bool): Whether to follow HTTP redirects (default: False)
59
        timeout (Timeout): Request timeout configuration (default: 5.0s)
60
        verify (bool | str | SSLContext): SSL certificate verification (default: True)
61
        trust_env (bool): Use environment variables for proxy/SSL config (default: True)
62
    
63
    Returns:
64
        Response: HTTP response object
65
    
66
    Raises:
67
        RequestError: If the request fails
68
    """
69
```
70

71
#### PUT Request
72

73
```python { .api }
74
def put(url, *, content=None, data=None, files=None, json=None, params=None, headers=None, cookies=None, auth=None, proxy=None, follow_redirects=False, timeout=DEFAULT_TIMEOUT_CONFIG, verify=True, trust_env=True):
75
    """
76
    Send a PUT request.
77
    
78
    Args:
79
        url (str): URL for the request
80
        content (bytes, optional): Raw bytes content for request body
81
        data (dict, optional): Form data to send in request body
82
        files (dict, optional): Files to upload
83
        json (any, optional): JSON-serializable object for request body
84
        params (dict, optional): Query parameters to append to URL
85
        headers (dict, optional): HTTP headers to send
86
        cookies (dict, optional): Cookies to send with request
87
        auth (Auth, optional): Authentication handler
88
        follow_redirects (bool): Whether to follow HTTP redirects (default: False)
89
        timeout (Timeout): Request timeout configuration (default: 5.0s)
90
        proxy (Proxy | str, optional): Proxy configuration
91
        verify (bool | str | SSLContext): SSL certificate verification (default: True)
92
        trust_env (bool): Use environment variables for proxy/SSL config (default: True)
93
    
94
    Returns:
95
        Response: HTTP response object
96
    
97
    Raises:
98
        RequestError: If the request fails
99
    """
100
```
101

102
#### PATCH Request
103

104
```python { .api }
105
def patch(url, *, content=None, data=None, files=None, json=None, params=None, headers=None, cookies=None, auth=None, proxy=None, follow_redirects=False, timeout=DEFAULT_TIMEOUT_CONFIG, verify=True, trust_env=True):
106
    """
107
    Send a PATCH request.
108
    
109
    Args:
110
        url (str): URL for the request
111
        content (bytes, optional): Raw bytes content for request body
112
        data (dict, optional): Form data to send in request body
113
        files (dict, optional): Files to upload
114
        json (any, optional): JSON-serializable object for request body
115
        params (dict, optional): Query parameters to append to URL
116
        headers (dict, optional): HTTP headers to send
117
        cookies (dict, optional): Cookies to send with request
118
        auth (Auth, optional): Authentication handler
119
        follow_redirects (bool): Whether to follow HTTP redirects (default: False)
120
        timeout (Timeout): Request timeout configuration (default: 5.0s)
121
        proxy (Proxy | str, optional): Proxy configuration
122
        verify (bool | str | SSLContext): SSL certificate verification (default: True)
123
        trust_env (bool): Use environment variables for proxy/SSL config (default: True)
124
    
125
    Returns:
126
        Response: HTTP response object
127
    
128
    Raises:
129
        RequestError: If the request fails
130
    """
131
```
132

133
#### DELETE Request
134

135
```python { .api }
136
def delete(url, *, params=None, headers=None, cookies=None, auth=None, proxy=None, follow_redirects=False, timeout=DEFAULT_TIMEOUT_CONFIG, verify=True, trust_env=True):
137
    """
138
    Send a DELETE request.
139
    
140
    Args:
141
        url (str): URL for the request
142
        params (dict, optional): Query parameters to append to URL
143
        headers (dict, optional): HTTP headers to send
144
        cookies (dict, optional): Cookies to send with request
145
        auth (Auth, optional): Authentication handler
146
        follow_redirects (bool): Whether to follow HTTP redirects (default: False)
147
        timeout (Timeout): Request timeout configuration (default: 5.0s)
148
        proxy (Proxy | str, optional): Proxy configuration
149
        verify (bool | str | SSLContext): SSL certificate verification (default: True)
150
        trust_env (bool): Use environment variables for proxy/SSL config (default: True)
151
    
152
    Returns:
153
        Response: HTTP response object
154
    
155
    Raises:
156
        RequestError: If the request fails
157
    """
158
```
159

160
#### HEAD Request
161

162
```python { .api }
163
def head(url, *, params=None, headers=None, cookies=None, auth=None, proxy=None, follow_redirects=False, timeout=DEFAULT_TIMEOUT_CONFIG, verify=True, trust_env=True):
164
    """
165
    Send a HEAD request.
166
    
167
    Args:
168
        url (str): URL for the request
169
        params (dict, optional): Query parameters to append to URL
170
        headers (dict, optional): HTTP headers to send
171
        cookies (dict, optional): Cookies to send with request
172
        auth (Auth, optional): Authentication handler
173
        follow_redirects (bool): Whether to follow HTTP redirects (default: False)
174
        timeout (Timeout): Request timeout configuration (default: 5.0s)
175
        proxy (Proxy | str, optional): Proxy configuration
176
        verify (bool | str | SSLContext): SSL certificate verification (default: True)
177
        trust_env (bool): Use environment variables for proxy/SSL config (default: True)
178
    
179
    Returns:
180
        Response: HTTP response object (with empty body)
181
    
182
    Raises:
183
        RequestError: If the request fails
184
    """
185
```
186

187
#### OPTIONS Request
188

189
```python { .api }
190
def options(url, *, params=None, headers=None, cookies=None, auth=None, proxy=None, follow_redirects=False, timeout=DEFAULT_TIMEOUT_CONFIG, verify=True, trust_env=True):
191
    """
192
    Send an OPTIONS request.
193
    
194
    Args:
195
        url (str): URL for the request
196
        params (dict, optional): Query parameters to append to URL
197
        headers (dict, optional): HTTP headers to send
198
        cookies (dict, optional): Cookies to send with request
199
        auth (Auth, optional): Authentication handler
200
        follow_redirects (bool): Whether to follow HTTP redirects (default: False)
201
        timeout (Timeout): Request timeout configuration (default: 5.0s)
202
        proxy (Proxy | str, optional): Proxy configuration
203
        verify (bool | str | SSLContext): SSL certificate verification (default: True)
204
        trust_env (bool): Use environment variables for proxy/SSL config (default: True)
205
    
206
    Returns:
207
        Response: HTTP response object
208
    
209
    Raises:
210
        RequestError: If the request fails
211
    """
212
```
213

214
#### Generic REQUEST Function
215

216
```python { .api }
217
def request(method, url, *, content=None, data=None, files=None, json=None, params=None, headers=None, cookies=None, auth=None, proxy=None, follow_redirects=False, timeout=DEFAULT_TIMEOUT_CONFIG, verify=True, trust_env=True):
218
    """
219
    Send an HTTP request with specified method.
220
    
221
    Args:
222
        method (str): HTTP method (GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS)
223
        url (str): URL for the request
224
        content (bytes, optional): Raw bytes content for request body
225
        data (dict, optional): Form data to send in request body
226
        files (dict, optional): Files to upload
227
        json (any, optional): JSON-serializable object for request body
228
        params (dict, optional): Query parameters to append to URL
229
        headers (dict, optional): HTTP headers to send
230
        cookies (dict, optional): Cookies to send with request
231
        auth (Auth, optional): Authentication handler
232
        follow_redirects (bool): Whether to follow HTTP redirects (default: False)
233
        timeout (Timeout): Request timeout configuration (default: 5.0s)
234
        proxy (Proxy | str, optional): Proxy configuration
235
        verify (bool | str | SSLContext): SSL certificate verification (default: True)
236
        trust_env (bool): Use environment variables for proxy/SSL config (default: True)
237
    
238
    Returns:
239
        Response: HTTP response object
240
    
241
    Raises:
242
        RequestError: If the request fails
243
    """
244
```
245

246
### Streaming Function
247

248
```python { .api }
249
def stream(method, url, **kwargs):
250
    """
251
    Stream a request response instead of loading it into memory.
252
    
253
    Args:
254
        method (str): HTTP method
255
        url (str): URL for the request
256
        **kwargs: Same arguments as request() function
257
    
258
    Returns:
259
        Generator yielding Response: Context manager that yields response for streaming
260
    
261
    Usage:
262
        with httpx.stream('GET', 'https://example.com/large-file') as response:
263
            for chunk in response.iter_bytes():
264
                process(chunk)
265
    """
266
```
267

268
## Usage Examples
269

270
### Simple GET Request
271

272
```python
273
import httpx
274

275
response = httpx.get('https://httpbin.org/get')
276
print(response.status_code)  # 200
277
print(response.json())       # Response data as dict
278
```
279

280
### POST with JSON Data
281

282
```python
283
import httpx
284

285
data = {'name': 'John', 'age': 30}
286
response = httpx.post('https://httpbin.org/post', json=data)
287
print(response.json()['json'])  # Echo of sent data
288
```
289

290
### POST with Form Data
291

292
```python
293
import httpx
294

295
data = {'username': 'user', 'password': 'pass'}
296
response = httpx.post('https://example.com/login', data=data)
297
```
298

299
### File Upload
300

301
```python
302
import httpx
303

304
files = {'file': ('report.csv', open('report.csv', 'rb'), 'text/csv')}
305
response = httpx.post('https://example.com/upload', files=files)
306
```
307

308
### Custom Headers and Parameters
309

310
```python
311
import httpx
312

313
headers = {'User-Agent': 'My-App/1.0'}
314
params = {'page': 1, 'limit': 10}
315

316
response = httpx.get(
317
    'https://api.example.com/data',
318
    headers=headers,
319
    params=params
320
)
321
```
322

323
### Authentication
324

325
```python
326
import httpx
327

328
auth = httpx.BasicAuth('username', 'password')
329
response = httpx.get('https://example.com/protected', auth=auth)
330
```
331

332
### Timeout Configuration
333

334
```python
335
import httpx
336

337
# Simple timeout
338
response = httpx.get('https://example.com', timeout=10.0)
339

340
# Detailed timeout
341
timeout = httpx.Timeout(10.0, connect=5.0)
342
response = httpx.get('https://example.com', timeout=timeout)
343
```