0
# Request Functions
1

2
High-level convenience functions for making HTTP requests without managing client instances. These functions provide a requests-compatible API with full support for all standard HTTP methods and modern features like HTTP/2, async capabilities, and comprehensive configuration options.
3

4
Each function creates a temporary client instance, makes the request, and cleans up automatically, making them ideal for one-off requests or simple scripts.
5

6
## Capabilities
7

8
### GET Requests
9

10
Performs HTTP GET requests for retrieving data from servers.
11

12
```python { .api }
13
def get(url, *, params=None, headers=None, cookies=None, stream=False, auth=None, allow_redirects=True, cert=None, verify=True, timeout=None):
14
    """
15
    Sends a GET request.
16

17
    Parameters:
18
    - url (URLTypes): URL for the request
19
    - params (QueryParamTypes, optional): Query parameters to append to URL
20
    - headers (HeaderTypes, optional): HTTP headers to send
21
    - cookies (CookieTypes, optional): Cookies to send
22
    - stream (bool): If True, download response content as a stream
23
    - auth (AuthTypes, optional): Authentication credentials
24
    - allow_redirects (bool): Whether to follow redirects (default: True)
25
    - cert (CertTypes, optional): Client certificate for SSL
26
    - verify (VerifyTypes): SSL certificate verification (default: True)
27
    - timeout (TimeoutTypes, optional): Request timeout configuration
28

29
    Returns:
30
    Response: HTTP response object
31
    """
32
```
33

34
**Usage Example:**
35

36
```python
37
import http3
38

39
# Simple GET request
40
response = http3.get('https://api.example.com/users')
41
print(response.json())
42

43
# GET with query parameters and headers
44
response = http3.get(
45
    'https://api.example.com/search',
46
    params={'q': 'python', 'limit': 10},
47
    headers={'Authorization': 'Bearer token'},
48
    timeout=30.0
49
)
50
```
51

52
### POST Requests
53

54
Performs HTTP POST requests for sending data to servers, including support for JSON, form data, and file uploads.
55

56
```python { .api }
57
def post(url, *, data=None, files=None, json=None, params=None, headers=None, cookies=None, stream=False, auth=None, allow_redirects=True, cert=None, verify=True, timeout=None):
58
    """
59
    Sends a POST request.
60

61
    Parameters:
62
    - url (URLTypes): URL for the request
63
    - data (RequestData, optional): Raw request body data
64
    - files (RequestFiles, optional): Files to upload (multipart/form-data)
65
    - json (Any, optional): JSON data to send (sets Content-Type to application/json)
66
    - params (QueryParamTypes, optional): Query parameters to append to URL
67
    - headers (HeaderTypes, optional): HTTP headers to send
68
    - cookies (CookieTypes, optional): Cookies to send
69
    - stream (bool): If True, download response content as a stream
70
    - auth (AuthTypes, optional): Authentication credentials
71
    - allow_redirects (bool): Whether to follow redirects (default: True)
72
    - cert (CertTypes, optional): Client certificate for SSL
73
    - verify (VerifyTypes): SSL certificate verification (default: True)
74
    - timeout (TimeoutTypes, optional): Request timeout configuration
75

76
    Returns:
77
    Response: HTTP response object
78
    """
79
```
80

81
**Usage Example:**
82

83
```python
84
import http3
85

86
# POST with JSON data
87
response = http3.post(
88
    'https://api.example.com/users',
89
    json={'name': 'John', 'email': 'john@example.com'}
90
)
91

92
# POST with form data
93
response = http3.post(
94
    'https://example.com/login',
95
    data={'username': 'user', 'password': 'pass'}
96
)
97

98
# POST with file upload
99
with open('document.pdf', 'rb') as f:
100
    response = http3.post(
101
        'https://api.example.com/upload',
102
        files={'file': f}
103
    )
104
```
105

106
### PUT Requests
107

108
Performs HTTP PUT requests for updating or creating resources on the server.
109

110
```python { .api }
111
def put(url, *, data=None, files=None, json=None, params=None, headers=None, cookies=None, stream=False, auth=None, allow_redirects=True, cert=None, verify=True, timeout=None):
112
    """
113
    Sends a PUT request.
114

115
    Parameters: Same as post()
116

117
    Returns:
118
    Response: HTTP response object
119
    """
120
```
121

122
### PATCH Requests
123

124
Performs HTTP PATCH requests for partial updates to resources.
125

126
```python { .api }
127
def patch(url, *, data=None, files=None, json=None, params=None, headers=None, cookies=None, stream=False, auth=None, allow_redirects=True, cert=None, verify=True, timeout=None):
128
    """
129
    Sends a PATCH request.
130

131
    Parameters: Same as post()
132

133
    Returns:
134
    Response: HTTP response object
135
    """
136
```
137

138
### DELETE Requests
139

140
Performs HTTP DELETE requests for removing resources from the server.
141

142
```python { .api }
143
def delete(url, *, data=None, files=None, json=None, params=None, headers=None, cookies=None, stream=False, auth=None, allow_redirects=True, cert=None, verify=True, timeout=None):
144
    """
145
    Sends a DELETE request.
146

147
    Parameters: Same as post()
148

149
    Returns:
150
    Response: HTTP response object
151
    """
152
```
153

154
### HEAD Requests
155

156
Performs HTTP HEAD requests to retrieve headers only (no response body).
157

158
```python { .api }
159
def head(url, *, params=None, headers=None, cookies=None, stream=False, auth=None, allow_redirects=False, cert=None, verify=True, timeout=None):
160
    """
161
    Sends a HEAD request.
162

163
    Parameters:
164
    - url (URLTypes): URL for the request
165
    - params (QueryParamTypes, optional): Query parameters to append to URL
166
    - headers (HeaderTypes, optional): HTTP headers to send
167
    - cookies (CookieTypes, optional): Cookies to send
168
    - stream (bool): If True, download response content as a stream
169
    - auth (AuthTypes, optional): Authentication credentials
170
    - allow_redirects (bool): Whether to follow redirects (default: False)
171
    - cert (CertTypes, optional): Client certificate for SSL
172
    - verify (VerifyTypes): SSL certificate verification (default: True)
173
    - timeout (TimeoutTypes, optional): Request timeout configuration
174

175
    Returns:
176
    Response: HTTP response object (with empty body)
177
    """
178
```
179

180
### OPTIONS Requests
181

182
Performs HTTP OPTIONS requests to query server capabilities and allowed methods.
183

184
```python { .api }
185
def options(url, *, params=None, headers=None, cookies=None, stream=False, auth=None, allow_redirects=True, cert=None, verify=True, timeout=None):
186
    """
187
    Sends an OPTIONS request.
188

189
    Parameters: Same as get()
190

191
    Returns:
192
    Response: HTTP response object
193
    """
194
```
195

196
### Generic Request Function
197

198
Performs HTTP requests with any method, providing maximum flexibility.
199

200
```python { .api }
201
def request(method, url, *, params=None, data=None, files=None, json=None, headers=None, cookies=None, auth=None, timeout=None, allow_redirects=True, cert=None, verify=True, stream=False):
202
    """
203
    Sends a request with the given HTTP method.
204

205
    Parameters:
206
    - method (str): HTTP method (GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS, etc.)
207
    - url (URLTypes): URL for the request
208
    - params (QueryParamTypes, optional): Query parameters to append to URL
209
    - data (RequestData, optional): Raw request body data
210
    - files (RequestFiles, optional): Files to upload (multipart/form-data)
211
    - json (Any, optional): JSON data to send
212
    - headers (HeaderTypes, optional): HTTP headers to send
213
    - cookies (CookieTypes, optional): Cookies to send
214
    - auth (AuthTypes, optional): Authentication credentials
215
    - timeout (TimeoutTypes, optional): Request timeout configuration
216
    - allow_redirects (bool): Whether to follow redirects (default: True)
217
    - cert (CertTypes, optional): Client certificate for SSL
218
    - verify (VerifyTypes): SSL certificate verification (default: True)
219
    - stream (bool): If True, download response content as a stream
220

221
    Returns:
222
    Response: HTTP response object
223
    """
224
```
225

226
**Usage Example:**
227

228
```python
229
import http3
230

231
# Custom HTTP method
232
response = http3.request('PROPFIND', 'https://webdav.example.com/files/')
233

234
# Custom method with full configuration
235
response = http3.request(
236
    'PATCH',
237
    'https://api.example.com/users/123',
238
    json={'status': 'active'},
239
    headers={'Content-Type': 'application/json'},
240
    timeout=10.0
241
)
242
```
243

244
## Common Parameters
245

246
All request functions support these common configuration parameters:
247

248
- **auth**: HTTP authentication (Basic Auth tuple or callable)
249
- **timeout**: Request timeout (float for all timeouts, or TimeoutConfig for granular control)
250
- **verify**: SSL certificate verification (bool or path to CA bundle)
251
- **cert**: Client SSL certificate (string path or tuple of cert/key paths)
252
- **allow_redirects**: Whether to automatically follow HTTP redirects
253
- **stream**: Enable streaming mode for large responses
254
- **headers**: Custom HTTP headers to include in the request
255
- **cookies**: Cookies to send with the request
256
- **params**: URL query parameters
257

258
## Error Handling
259

260
All request functions may raise these exceptions:
261

262
- **ConnectTimeout**: Connection establishment timeout
263
- **ReadTimeout**: Response reading timeout  
264
- **WriteTimeout**: Request sending timeout
265
- **TooManyRedirects**: Exceeded maximum redirect limit
266
- **InvalidURL**: Malformed URL provided
267
- **ProtocolError**: HTTP protocol violation
268
- **DecodingError**: Response content decoding failure