0
# HTTP Methods
1

2
Core HTTP method functions that provide the primary interface for making HTTP requests. These functions handle the most common HTTP verbs and automatically manage sessions internally.
3

4
## Capabilities
5

6
### Main Request Function
7

8
The core request function that all other HTTP method functions use internally. Provides full control over HTTP method and request parameters.
9

10
```python { .api }
11
def request(method: str, url: str, **kwargs) -> Response:
12
    """
13
    Constructs and sends a Request.
14

15
    Parameters:
16
    - method: HTTP method ('GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS')
17
    - url: URL for the request
18
    - params: dict, list of tuples or bytes for query string parameters
19
    - data: dict, list of tuples, bytes, or file-like object for request body
20
    - json: JSON serializable Python object for request body
21
    - headers: dict of HTTP headers
22
    - cookies: dict or CookieJar object
23
    - files: dict of file-like objects for multipart encoding
24
    - auth: auth tuple or auth handler instance
25
    - timeout: float or (connect timeout, read timeout) tuple in seconds
26
    - allow_redirects: bool to enable/disable redirects
27
    - proxies: dict mapping protocol to proxy URL
28
    - verify: bool or path to CA bundle for SSL verification
29
    - stream: bool to download response content immediately
30
    - cert: path to SSL client cert file or (cert, key) tuple
31

32
    Returns:
33
    Response object
34
    """
35
```
36

37
### GET Requests
38

39
Send HTTP GET requests to retrieve data from servers.
40

41
```python { .api }
42
def get(url: str, params=None, **kwargs) -> Response:
43
    """
44
    Sends a GET request.
45

46
    Parameters:
47
    - url: URL for the request
48
    - params: dict, list of tuples or bytes for query string parameters
49
    - **kwargs: optional arguments that request() accepts
50

51
    Returns:
52
    Response object
53
    """
54
```
55

56
Usage example:
57

58
```python
59
import requests
60

61
# Simple GET request
62
response = requests.get('https://api.github.com/users/octocat')
63

64
# GET with query parameters
65
params = {'q': 'python', 'sort': 'stars'}
66
response = requests.get('https://api.github.com/search/repositories', params=params)
67

68
# GET with headers and authentication
69
headers = {'User-Agent': 'MyApp/1.0'}
70
response = requests.get('https://api.example.com/data', 
71
                       headers=headers, 
72
                       auth=('username', 'password'))
73
```
74

75
### POST Requests
76

77
Send HTTP POST requests to submit data to servers.
78

79
```python { .api }
80
def post(url: str, data=None, json=None, **kwargs) -> Response:
81
    """
82
    Sends a POST request.
83

84
    Parameters:
85
    - url: URL for the request
86
    - data: dict, list of tuples, bytes, or file-like object for request body
87
    - json: JSON serializable Python object for request body
88
    - **kwargs: optional arguments that request() accepts
89

90
    Returns:
91
    Response object
92
    """
93
```
94

95
Usage example:
96

97
```python
98
import requests
99

100
# POST with form data
101
data = {'key1': 'value1', 'key2': 'value2'}
102
response = requests.post('https://httpbin.org/post', data=data)
103

104
# POST with JSON data
105
json_data = {'user': 'john', 'age': 30}
106
response = requests.post('https://api.example.com/users', json=json_data)
107

108
# POST with file upload
109
files = {'file': open('document.pdf', 'rb')}
110
response = requests.post('https://httpbin.org/post', files=files)
111
```
112

113
### PUT Requests
114

115
Send HTTP PUT requests to create or update resources.
116

117
```python { .api }
118
def put(url: str, data=None, **kwargs) -> Response:
119
    """
120
    Sends a PUT request.
121

122
    Parameters:
123
    - url: URL for the request
124
    - data: dict, list of tuples, bytes, or file-like object for request body
125
    - **kwargs: optional arguments that request() accepts
126

127
    Returns:
128
    Response object
129
    """
130
```
131

132
### PATCH Requests
133

134
Send HTTP PATCH requests to partially update resources.
135

136
```python { .api }
137
def patch(url: str, data=None, **kwargs) -> Response:
138
    """
139
    Sends a PATCH request.
140

141
    Parameters:
142
    - url: URL for the request
143
    - data: dict, list of tuples, bytes, or file-like object for request body
144
    - **kwargs: optional arguments that request() accepts
145

146
    Returns:
147
    Response object
148
    """
149
```
150

151
### DELETE Requests
152

153
Send HTTP DELETE requests to remove resources.
154

155
```python { .api }
156
def delete(url: str, **kwargs) -> Response:
157
    """
158
    Sends a DELETE request.
159

160
    Parameters:
161
    - url: URL for the request
162
    - **kwargs: optional arguments that request() accepts
163

164
    Returns:
165
    Response object
166
    """
167
```
168

169
### HEAD Requests
170

171
Send HTTP HEAD requests to retrieve headers without response body.
172

173
```python { .api }
174
def head(url: str, **kwargs) -> Response:
175
    """
176
    Sends a HEAD request.
177

178
    Parameters:
179
    - url: URL for the request
180
    - **kwargs: optional arguments that request() accepts
181
    Note: allow_redirects defaults to False for HEAD requests
182

183
    Returns:
184
    Response object with empty content
185
    """
186
```
187

188
### OPTIONS Requests
189

190
Send HTTP OPTIONS requests to determine allowed methods and capabilities.
191

192
```python { .api }
193
def options(url: str, **kwargs) -> Response:
194
    """
195
    Sends an OPTIONS request.
196

197
    Parameters:
198
    - url: URL for the request
199
    - **kwargs: optional arguments that request() accepts
200

201
    Returns:
202
    Response object
203
    """
204
```
205

206
## Common Parameters
207

208
All HTTP method functions accept these common optional parameters:
209

210
- **headers**: `Dict[str, str]` - HTTP headers to send
211
- **auth**: `AuthType` - Authentication tuple or handler
212
- **timeout**: `Union[float, Tuple[float, float]]` - Request timeout in seconds
213
- **proxies**: `Dict[str, str]` - Proxy configuration
214
- **verify**: `Union[bool, str]` - SSL certificate verification
215
- **cert**: `Union[str, Tuple[str, str]]` - Client certificate
216
- **stream**: `bool` - Stream download response content
217
- **allow_redirects**: `bool` - Follow redirects (default True, except HEAD)
218
- **cookies**: `CookiesType` - Cookies to send
219

220
## Error Handling
221

222
All HTTP method functions can raise these exceptions:
223

224
- **RequestException**: Base exception for all request-related errors
225
- **HTTPError**: 4xx or 5xx status codes (when raise_for_status() is called)
226
- **ConnectionError**: Connection-related errors
227
- **Timeout**: Request timeout errors
228
- **URLRequired**: Invalid or missing URL