0
# Synchronous HTTP Requests
1

2
Core HTTP methods for making synchronous requests. These functions provide a simple interface for HTTP communication without requiring explicit session management. Each request creates a new connection that is automatically closed after completion.
3

4
## Capabilities
5

6
### Generic Request Function
7

8
The fundamental request function that all other HTTP methods build upon. Supports all HTTP methods and provides complete control over request parameters.
9

10
```python { .api }
11
def request(
12
    method: HttpMethodType,
13
    url: str,
14
    *,
15
    params: QueryParameterType | None = None,
16
    data: BodyType | None = None,
17
    json: Any | None = None,
18
    headers: HeadersType | None = None,
19
    cookies: CookiesType | None = None,
20
    files: MultiPartFilesType | MultiPartFilesAltType | None = None,
21
    auth: HttpAuthenticationType | None = None,
22
    timeout: TimeoutType | None = WRITE_DEFAULT_TIMEOUT,
23
    allow_redirects: bool = True,
24
    proxies: ProxyType | None = None,
25
    verify: TLSVerifyType = True,
26
    stream: bool = False,
27
    cert: TLSClientCertType | None = None,
28
    hooks: HookType[PreparedRequest | Response] | None = None,
29
    retries: RetryType = DEFAULT_RETRIES,
30
) -> Response:
31
    """
32
    Constructs and sends a Request with the specified HTTP method.
33
    
34
    Args:
35
        method: HTTP method (GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS)
36
        url: Target URL for the request
37
        params: Query parameters to append to URL
38
        data: Request body data (dict, list, bytes, or file-like object)
39
        json: JSON serializable object to send in request body
40
        headers: HTTP headers to include in request
41
        cookies: Cookies to send with request
42
        files: Files for multipart upload
43
        auth: Authentication credentials
44
        timeout: Request timeout in seconds
45
        allow_redirects: Whether to follow HTTP redirects
46
        proxies: Proxy configuration
47
        verify: SSL certificate verification (bool or CA bundle path)
48
        stream: Whether to download response immediately
49
        cert: Client SSL certificate
50
        hooks: Request/response lifecycle hooks
51
        retries: Retry configuration
52
        
53
    Returns:
54
        Response object containing server response
55
    """
56
```
57

58
### GET Requests
59

60
Retrieves data from the specified URL. Commonly used for fetching web pages, API responses, and downloadable content.
61

62
```python { .api }
63
def get(
64
    url: str,
65
    params: QueryParameterType | None = None,
66
    *,
67
    headers: HeadersType | None = None,
68
    cookies: CookiesType | None = None,
69
    auth: HttpAuthenticationType | None = None,
70
    timeout: TimeoutType | None = READ_DEFAULT_TIMEOUT,
71
    allow_redirects: bool = True,
72
    proxies: ProxyType | None = None,
73
    verify: TLSVerifyType = True,
74
    stream: bool = False,
75
    cert: TLSClientCertType | None = None,
76
    hooks: HookType[PreparedRequest | Response] | None = None,
77
    retries: RetryType = DEFAULT_RETRIES,
78
    **kwargs: Any,
79
) -> Response:
80
    """
81
    Sends a GET request to retrieve data from the specified URL.
82
    
83
    Args:
84
        url: Target URL
85
        params: Query parameters to append to URL
86
        headers: HTTP headers
87
        cookies: Cookies to send
88
        auth: Authentication credentials
89
        timeout: Request timeout (defaults to read timeout)
90
        allow_redirects: Follow redirects (default: True)
91
        proxies: Proxy configuration
92
        verify: SSL verification
93
        stream: Stream response content
94
        cert: Client certificate
95
        hooks: Request hooks
96
        retries: Retry configuration
97
        **kwargs: Additional arguments
98
        
99
    Returns:
100
        Response object
101
    """
102
```
103

104
Usage example:
105

106
```python
107
# Simple GET request
108
response = niquests.get('https://api.example.com/data')
109

110
# GET with query parameters
111
params = {'q': 'search term', 'limit': 10}
112
response = niquests.get('https://api.example.com/search', params=params)
113

114
# GET with custom headers
115
headers = {'User-Agent': 'MyApp/1.0', 'Accept': 'application/json'}
116
response = niquests.get('https://api.example.com/data', headers=headers)
117
```
118

119
### POST Requests
120

121
Sends data to the server for processing. Commonly used for form submissions, API data creation, and file uploads.
122

123
```python { .api }
124
def post(
125
    url: str,
126
    data: BodyType | None = None,
127
    json: Any | None = None,
128
    *,
129
    params: QueryParameterType | None = None,
130
    headers: HeadersType | None = None,
131
    cookies: CookiesType | None = None,
132
    files: MultiPartFilesType | MultiPartFilesAltType | None = None,
133
    auth: HttpAuthenticationType | None = None,
134
    timeout: TimeoutType | None = WRITE_DEFAULT_TIMEOUT,
135
    allow_redirects: bool = True,
136
    proxies: ProxyType | None = None,
137
    verify: TLSVerifyType = True,
138
    stream: bool = False,
139
    cert: TLSClientCertType | None = None,
140
    hooks: HookType[PreparedRequest | Response] | None = None,
141
    retries: RetryType = DEFAULT_RETRIES,
142
) -> Response:
143
    """
144
    Sends a POST request with optional data payload.
145
    
146
    Args:
147
        url: Target URL
148
        data: Request body data
149
        json: JSON data to serialize and send
150
        params: Query parameters
151
        headers: HTTP headers
152
        cookies: Cookies
153
        files: Files for multipart upload
154
        auth: Authentication
155
        timeout: Request timeout (defaults to write timeout)
156
        allow_redirects: Follow redirects
157
        proxies: Proxy configuration
158
        verify: SSL verification
159
        stream: Stream response
160
        cert: Client certificate
161
        hooks: Request hooks
162
        retries: Retry configuration
163
        
164
    Returns:
165
        Response object
166
    """
167
```
168

169
Usage example:
170

171
```python
172
# POST with JSON data
173
data = {'name': 'John Doe', 'email': 'john@example.com'}
174
response = niquests.post('https://api.example.com/users', json=data)
175

176
# POST with form data
177
form_data = {'username': 'john', 'password': 'secret'}
178
response = niquests.post('https://example.com/login', data=form_data)
179

180
# POST with file upload
181
files = {'upload': open('document.pdf', 'rb')}
182
response = niquests.post('https://api.example.com/upload', files=files)
183
```
184

185
### PUT Requests
186

187
Updates or replaces a resource on the server. Typically used for full resource updates in REST APIs.
188

189
```python { .api }
190
def put(
191
    url: str,
192
    data: BodyType | None = None,
193
    *,
194
    json: Any | None = None,
195
    params: QueryParameterType | None = None,
196
    headers: HeadersType | None = None,
197
    cookies: CookiesType | None = None,
198
    files: MultiPartFilesType | MultiPartFilesAltType | None = None,
199
    auth: HttpAuthenticationType | None = None,
200
    timeout: TimeoutType | None = WRITE_DEFAULT_TIMEOUT,
201
    allow_redirects: bool = True,
202
    proxies: ProxyType | None = None,
203
    verify: TLSVerifyType = True,
204
    stream: bool = False,
205
    cert: TLSClientCertType | None = None,
206
    hooks: HookType[PreparedRequest | Response] | None = None,
207
    retries: RetryType = DEFAULT_RETRIES,
208
) -> Response:
209
    """
210
    Sends a PUT request to update or replace a resource.
211
    
212
    Args:
213
        url: Target URL
214
        data: Request body data
215
        json: JSON data to serialize and send
216
        params: Query parameters
217
        headers: HTTP headers
218
        cookies: Cookies
219
        files: Files for multipart upload
220
        auth: Authentication
221
        timeout: Request timeout
222
        allow_redirects: Follow redirects
223
        proxies: Proxy configuration
224
        verify: SSL verification
225
        stream: Stream response
226
        cert: Client certificate
227
        hooks: Request hooks
228
        retries: Retry configuration
229
        
230
    Returns:
231
        Response object
232
    """
233
```
234

235
### PATCH Requests
236

237
Partially updates a resource on the server. Used for incremental updates in REST APIs.
238

239
```python { .api }
240
def patch(
241
    url: str,
242
    data: BodyType | None = None,
243
    *,
244
    json: Any | None = None,
245
    params: QueryParameterType | None = None,
246
    headers: HeadersType | None = None,
247
    cookies: CookiesType | None = None,
248
    files: MultiPartFilesType | MultiPartFilesAltType | None = None,
249
    auth: HttpAuthenticationType | None = None,
250
    timeout: TimeoutType | None = WRITE_DEFAULT_TIMEOUT,
251
    allow_redirects: bool = True,
252
    proxies: ProxyType | None = None,
253
    verify: TLSVerifyType = True,
254
    stream: bool = False,
255
    cert: TLSClientCertType | None = None,
256
    hooks: HookType[PreparedRequest | Response] | None = None,
257
    retries: RetryType = DEFAULT_RETRIES,
258
) -> Response:
259
    """
260
    Sends a PATCH request for partial resource updates.
261
    """
262
```
263

264
### DELETE Requests
265

266
Removes a resource from the server. Used for resource deletion in REST APIs.
267

268
```python { .api }
269
def delete(
270
    url: str,
271
    *,
272
    params: QueryParameterType | None = None,
273
    headers: HeadersType | None = None,
274
    cookies: CookiesType | None = None,
275
    auth: HttpAuthenticationType | None = None,
276
    timeout: TimeoutType | None = WRITE_DEFAULT_TIMEOUT,
277
    allow_redirects: bool = True,
278
    proxies: ProxyType | None = None,
279
    verify: TLSVerifyType = True,
280
    stream: bool = False,
281
    cert: TLSClientCertType | None = None,
282
    hooks: HookType[PreparedRequest | Response] | None = None,
283
    retries: RetryType = DEFAULT_RETRIES,
284
    **kwargs: Any,
285
) -> Response:
286
    """
287
    Sends a DELETE request to remove a resource.
288
    """
289
```
290

291
### HEAD Requests
292

293
Retrieves only the headers from a resource without downloading the body content. Useful for checking resource metadata, existence, or last-modified dates.
294

295
```python { .api }
296
def head(
297
    url: str,
298
    *,
299
    params: QueryParameterType | None = None,
300
    headers: HeadersType | None = None,
301
    cookies: CookiesType | None = None,
302
    auth: HttpAuthenticationType | None = None,
303
    timeout: TimeoutType | None = READ_DEFAULT_TIMEOUT,
304
    allow_redirects: bool = False,
305
    proxies: ProxyType | None = None,
306
    verify: TLSVerifyType = True,
307
    stream: bool = False,
308
    cert: TLSClientCertType | None = None,
309
    hooks: HookType[PreparedRequest | Response] | None = None,
310
    retries: RetryType = DEFAULT_RETRIES,
311
    **kwargs: Any,
312
) -> Response:
313
    """
314
    Sends a HEAD request to retrieve only response headers.
315
    
316
    Note: allow_redirects defaults to False for HEAD requests.
317
    """
318
```
319

320
### OPTIONS Requests
321

322
Queries the server for supported HTTP methods and capabilities for a specific resource. Used for CORS preflight requests and API discovery.
323

324
```python { .api }
325
def options(
326
    url: str,
327
    *,
328
    params: QueryParameterType | None = None,
329
    headers: HeadersType | None = None,
330
    cookies: CookiesType | None = None,
331
    auth: HttpAuthenticationType | None = None,
332
    timeout: TimeoutType | None = READ_DEFAULT_TIMEOUT,
333
    allow_redirects: bool = True,
334
    proxies: ProxyType | None = None,
335
    verify: TLSVerifyType = True,
336
    stream: bool = False,
337
    cert: TLSClientCertType | None = None,
338
    hooks: HookType[PreparedRequest | Response] | None = None,
339
    retries: RetryType = DEFAULT_RETRIES,
340
    **kwargs: Any,
341
) -> Response:
342
    """
343
    Sends an OPTIONS request to query server capabilities.
344
    """
345
```
346

347
## Common Parameters
348

349
All synchronous HTTP methods support these common parameters:
350

351
### Request Configuration
352
- **url**: Target URL (required)
353
- **params**: Query parameters (dict, list of tuples, or bytes)
354
- **headers**: HTTP headers (dict)
355
- **cookies**: Cookies (dict or CookieJar object)
356
- **auth**: Authentication (tuple for Basic auth or custom Auth object)
357

358
### Request Body (POST/PUT/PATCH)
359
- **data**: Request body data (dict, list, bytes, or file-like object)
360
- **json**: JSON-serializable object (automatically sets Content-Type)
361
- **files**: Files for multipart upload (dict of name: file-like-object pairs)
362

363
### Network Configuration
364
- **timeout**: Request timeout (float, tuple, or TimeoutConfiguration)
365
- **allow_redirects**: Follow HTTP redirects (boolean, defaults vary by method)
366
- **proxies**: Proxy settings (dict mapping protocols to proxy URLs)
367
- **verify**: SSL certificate verification (boolean or CA bundle path)
368
- **cert**: Client SSL certificate (string path or tuple)
369

370
### Advanced Options
371
- **stream**: Download response content immediately (boolean)
372
- **hooks**: Request/response lifecycle hooks (dict)
373
- **retries**: Retry configuration (integer or RetryConfiguration object)
374

375
## Type Definitions
376

377
```python { .api }
378
HttpMethodType = Literal["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"]
379
QueryParameterType = Union[dict, list, bytes]
380
HeadersType = Union[dict, Headers]
381
CookiesType = Union[dict, RequestsCookieJar]
382
BodyType = Union[str, bytes, dict, list, IOBase]
383
TimeoutType = Union[float, Tuple[float, float], TimeoutConfiguration]
384
TLSVerifyType = Union[bool, str, bytes]
385
TLSClientCertType = Union[str, Tuple[str, str], Tuple[str, str, str]]
386
ProxyType = dict
387
RetryType = Union[int, RetryConfiguration]
388
HookType = dict
389
```