0
# Simple Requests
1

2
High-level request interface that provides convenient functions for making HTTP requests without needing to manage connection pools directly. These functions use a module-global PoolManager instance for automatic connection management.
3

4
## Capabilities
5

6
### Module-Level Request Function
7

8
Makes HTTP requests using a shared global PoolManager instance. This is the simplest way to make HTTP requests with urllib3, suitable for scripts and applications that don't need fine-grained connection management.
9

10
```python { .api }
11
def request(method: str, url: str, *, body=None, fields=None, headers=None,
12
           preload_content=True, decode_content=True, redirect=True,
13
           retries=None, timeout=3, json=None) -> BaseHTTPResponse:
14
    """
15
    A convenience, top-level request method using a module-global PoolManager instance.
16

17
    Parameters:
18
    - method: HTTP request method (GET, POST, PUT, DELETE, etc.)
19
    - url: The URL to perform the request on
20
    - body: Data to send in the request body (str, bytes, iterable, or file-like)
21
    - fields: Data to encode and send in the request body (multipart form data)
22
    - headers: Dictionary of custom headers to send
23
    - preload_content: If True, response body will be preloaded into memory
24
    - decode_content: If True, attempt to decode body based on content-encoding
25
    - redirect: If True, automatically handle redirects (301, 302, 303, 307, 308)
26
    - retries: Configure retry behavior (Retry object, int, bool, or None)
27
    - timeout: Request timeout in seconds (float, int, or Timeout object)
28
    - json: Data to encode and send as JSON with UTF-8 encoding
29

30
    Returns:
31
    BaseHTTPResponse: Response object with status, headers, and data
32
    """
33
```
34

35
### Usage Examples
36

37
#### Basic GET Request
38

39
```python
40
import urllib3
41

42
# Simple GET request
43
resp = urllib3.request('GET', 'https://httpbin.org/get')
44
print(f"Status: {resp.status}")
45
print(f"Data: {resp.data.decode('utf-8')}")
46
```
47

48
#### POST with Form Data
49

50
```python
51
import urllib3
52

53
# POST request with form fields
54
resp = urllib3.request('POST', 'https://httpbin.org/post',
55
                      fields={'username': 'john', 'password': 'secret'})
56
print(f"Status: {resp.status}")
57
```
58

59
#### POST with JSON Data
60

61
```python
62
import urllib3
63

64
# POST request with JSON body
65
resp = urllib3.request('POST', 'https://httpbin.org/post',
66
                      json={'message': 'Hello, World!'})
67
print(f"Status: {resp.status}")
68
```
69

70
#### Custom Headers and Timeout
71

72
```python
73
import urllib3
74

75
# Request with custom headers and timeout
76
resp = urllib3.request('GET', 'https://httpbin.org/headers',
77
                      headers={'User-Agent': 'MyApp/1.0'},
78
                      timeout=10)
79
print(f"Status: {resp.status}")
80
```
81

82
#### Retry Configuration
83

84
```python
85
import urllib3
86

87
# Request with custom retry behavior
88
retries = urllib3.Retry(total=5, backoff_factor=0.3)
89
resp = urllib3.request('GET', 'https://httpbin.org/get',
90
                      retries=retries)
91
```
92

93
### Request Body Types
94

95
The `body` parameter accepts various data types:
96

97
- **str**: String data (encoded as UTF-8)
98
- **bytes**: Raw byte data
99
- **Iterable**: Iterable of str/bytes for streaming data
100
- **File-like object**: Any object with a `read()` method
101

102
### Response Handling
103

104
All requests return a `BaseHTTPResponse` object with:
105

106
- `status`: HTTP status code (int)
107
- `headers`: Response headers (HTTPHeaderDict)
108
- `data`: Response body as bytes
109
- `read()`: Method to read response data in chunks
110
- `json()`: Method to parse JSON response data