### GET https://httpbin.org/get (with query parameters)

Source: https://github.com/psf/requests/blob/main/docs/user/quickstart.rst

Sends a GET request to httpbin.org/get, demonstrating how to pass query parameters in the URL.

```APIDOC
## GET https://httpbin.org/get

### Description
Sends a GET request to httpbin.org/get, demonstrating how to pass query parameters in the URL.

### Method
GET

### Endpoint
https://httpbin.org/get

### Parameters
#### Path Parameters
None

#### Query Parameters
- **key1** (string) - Required - The first key-value pair for the query string.
- **key2** (string or array of strings) - Required - The second key-value pair for the query string. Can be a single value or a list of values.

#### Request Body
None

### Request Example
N/A

### Response
#### Success Response (200)
- **(object)** - httpbin.org echoes the received query parameters within the response.

#### Response Example
https://httpbin.org/get?key2=value2&key1=value1
```

--------------------------------

### GET https://api.github.com/events

Source: https://github.com/psf/requests/blob/main/docs/user/quickstart.rst

Makes a GET request to retrieve public events from the GitHub API. This is a basic example of fetching data from a REST API.

```APIDOC
## GET https://api.github.com/events

### Description
Makes a GET request to retrieve public events from the GitHub API. This is a basic example of fetching data from a REST API.

### Method
GET

### Endpoint
https://api.github.com/events

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
N/A

### Response
#### Success Response (200)
- **(array of objects)** - A JSON array representing various GitHub events.

#### Response Example
[{"repository":{"open_issues":0,"url":"https://github.com/..."}}]
```

--------------------------------

### Make a basic HTTP GET request with Python Requests

Source: https://github.com/psf/requests/blob/main/docs/user/quickstart.rst

This snippet shows how to perform a simple HTTP GET request to retrieve data from a specified URL using the `requests.get()` method. The response is captured in a `Response` object for further processing.

```python
r = requests.get('https://api.github.com/events')
```

--------------------------------

### OPTIONS https://httpbin.org/get

Source: https://github.com/psf/requests/blob/main/docs/user/quickstart.rst

Sends an OPTIONS request to httpbin.org/get. This queries the server for supported HTTP methods and other communication options.

```APIDOC
## OPTIONS https://httpbin.org/get

### Description
Sends an OPTIONS request to httpbin.org/get. This queries the server for supported HTTP methods and other communication options.

### Method
OPTIONS

### Endpoint
https://httpbin.org/get

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
N/A

### Response
#### Success Response (200)
- **(headers only)** - The response typically contains an 'Allow' header indicating supported methods.

#### Response Example
N/A
```

--------------------------------

### POST https://httpbin.org/post

Source: https://github.com/psf/requests/blob/main/docs/user/quickstart.rst

Sends a POST request to httpbin.org/post with simple form-encoded data in the request body.

```APIDOC
## POST https://httpbin.org/post

### Description
Sends a POST request to httpbin.org/post with simple form-encoded data in the request body.

### Method
POST

### Endpoint
https://httpbin.org/post

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **key** (string) - Required - A key for the form data.
- **value** (string) - Required - The value associated with the key.

### Request Example
{
  "key": "value"
}

### Response
#### Success Response (200)
- **(object)** - httpbin.org echoes the received request data.

#### Response Example
N/A
```

--------------------------------

### HEAD https://httpbin.org/get

Source: https://github.com/psf/requests/blob/main/docs/user/quickstart.rst

Sends a HEAD request to httpbin.org/get. This retrieves the response headers only, without the response body.

```APIDOC
## HEAD https://httpbin.org/get

### Description
Sends a HEAD request to httpbin.org/get. This retrieves the response headers only, without the response body.

### Method
HEAD

### Endpoint
https://httpbin.org/get

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
N/A

### Response
#### Success Response (200)
- **(headers only)** - The response will contain only HTTP headers.

#### Response Example
N/A
```

--------------------------------

### DELETE https://httpbin.org/delete

Source: https://github.com/psf/requests/blob/main/docs/user/quickstart.rst

Sends a DELETE request to httpbin.org/delete. This typically indicates resource deletion.

```APIDOC
## DELETE https://httpbin.org/delete

### Description
Sends a DELETE request to httpbin.org/delete. This typically indicates resource deletion.

### Method
DELETE

### Endpoint
https://httpbin.org/delete

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
N/A

### Response
#### Success Response (200)
- **(object)** - httpbin.org confirms the deletion request.

#### Response Example
N/A
```

--------------------------------

### Send Custom Cookies with Requests in Python

Source: https://github.com/psf/requests/blob/main/docs/user/quickstart.rst

This example shows how to include custom cookies in an HTTP GET request using the `cookies` parameter of the `requests.get()` method. The server's response confirms the cookies were received.

```python
url = 'https://httpbin.org/cookies'
cookies = dict(cookies_are='working')

r = requests.get(url, cookies=cookies)
r.text
```

--------------------------------

### Install Requests from local source directory

Source: https://github.com/psf/requests/blob/main/docs/user/install.rst

After navigating into the Requests source directory, this command installs the library into your Python environment. This method is useful when you have cloned or downloaded the source code and wish to install a local version for development or specific testing.

```shell
cd requests
python -m pip install .
```

--------------------------------

### Track Redirection History in Requests in Python

Source: https://github.com/psf/requests/blob/main/docs/user/quickstart.rst

This example demonstrates how Requests automatically handles HTTP to HTTPS redirection and how to access the final URL, status code, and the history of redirect responses using the `r.url`, `r.status_code`, and `r.history` attributes.

```python
r = requests.get('http://github.com/')

r.url
'https://github.com/'

r.status_code
200

r.history
[<Response [301]>]
```

--------------------------------

### Enable Redirection for HEAD Requests in Python

Source: https://github.com/psf/requests/blob/main/docs/user/quickstart.rst

By default, HEAD requests do not follow redirects. This example demonstrates how to explicitly enable redirection for a HEAD request using `allow_redirects=True` and then inspect the final URL and redirection history.

```python
r = requests.head('http://github.com/', allow_redirects=True)

r.url
'https://github.com/'

r.history
[<Response [301]>]
```

--------------------------------

### Import Requests library in Python

Source: https://github.com/psf/requests/blob/main/docs/user/quickstart.rst

This snippet demonstrates how to import the 'requests' library, which is the foundational step for performing HTTP requests in Python.

```python
import requests
```

--------------------------------

### Manage Cookies with RequestsCookieJar in Python

Source: https://github.com/psf/requests/blob/main/docs/user/quickstart.rst

This snippet illustrates how to create and populate a `requests.cookies.RequestsCookieJar` object with multiple cookies, specifying domain and path. The cookie jar is then passed to a GET request to demonstrate its usage for sending specific cookies.

```python
jar = requests.cookies.RequestsCookieJar()
jar.set('tasty_cookie', 'yum', domain='httpbin.org', path='/cookies')
jar.set('gross_cookie', 'blech', domain='httpbin.org', path='/elsewhere')
url = 'https://httpbin.org/cookies'
r = requests.get(url, cookies=jar)
r.text
```

--------------------------------

### PUT https://httpbin.org/put

Source: https://github.com/psf/requests/blob/main/docs/user/quickstart.rst

Sends a PUT request to httpbin.org/put with simple form-encoded data in the request body.

```APIDOC
## PUT https://httpbin.org/put

### Description
Sends a PUT request to httpbin.org/put with simple form-encoded data in the request body.

### Method
PUT

### Endpoint
https://httpbin.org/put

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **key** (string) - Required - A key for the form data.
- **value** (string) - Required - The value associated with the key.

### Request Example
{
  "key": "value"
}

### Response
#### Success Response (200)
- **(object)** - httpbin.org echoes the received request data.

#### Response Example
N/A
```

--------------------------------

### Install Requests using pip

Source: https://github.com/psf/requests/blob/main/docs/user/install.rst

This command installs the Requests library from PyPI using pip, the standard Python package installer. It ensures all necessary dependencies are met and the library is globally available for your Python environment.

```shell
python -m pip install requests
```

--------------------------------

### Access Specific HTTP Response Header Case-Insensitively with Requests in Python

Source: https://github.com/psf/requests/blob/main/docs/user/quickstart.rst

Demonstrates accessing individual HTTP response headers using dictionary-like indexing or the 'get()' method. The 'headers' object handles case-insensitivity for header names as per RFC 7230.

```python
r.headers['Content-Type']

r.headers.get('content-type')
```

--------------------------------

### Access Cookies from Requests Response in Python

Source: https://github.com/psf/requests/blob/main/docs/user/quickstart.rst

This snippet demonstrates how to send an HTTP GET request to a URL and then access a specific cookie from the `Response` object returned by the `requests` library.

```python
url = 'http://example.com/some/cookie/setting/url'
r = requests.get(url)

r.cookies['example_cookie_name']
```

--------------------------------

### Clone Requests source code from GitHub

Source: https://github.com/psf/requests/blob/main/docs/user/install.rst

This command uses Git to clone the entire Requests project repository from GitHub. Cloning provides access to the full development history and allows for local modifications or contributions.

```shell
git clone https://github.com/psf/requests.git
```

--------------------------------

### Perform various HTTP methods (POST, PUT, DELETE, HEAD, OPTIONS) with Python Requests

Source: https://github.com/psf/requests/blob/main/docs/user/quickstart.rst

This snippet illustrates how to execute different types of HTTP requests, including POST, PUT, DELETE, HEAD, and OPTIONS, using their respective methods in the Requests library. It demonstrates providing data for POST and PUT requests.

```python
r = requests.post('https://httpbin.org/post', data={'key': 'value'})
r = requests.put('https://httpbin.org/put', data={'key': 'value'})
r = requests.delete('https://httpbin.org/delete')
r = requests.head('https://httpbin.org/get')
r = requests.options('https://httpbin.org/get')
```

--------------------------------

### Compare HTTP Response Status with Requests.codes in Python

Source: https://github.com/psf/requests/blob/main/docs/user/quickstart.rst

Illustrates using the built-in 'requests.codes' object for semantic comparison of HTTP status codes. This improves readability by using named constants instead of raw numbers.

```python
r.status_code == requests.codes.ok
```

--------------------------------

### Create an image from binary HTTP response content using Python PIL

Source: https://github.com/psf/requests/blob/main/docs/user/quickstart.rst

This snippet demonstrates how to process and create an image from binary data obtained via an HTTP request. It utilizes the Pillow (PIL) library and `io.BytesIO` to treat the `r.content` byte stream as a file-like object for image creation.

```python
from PIL import Image
from io import BytesIO

i = Image.open(BytesIO(r.content))
```

--------------------------------

### Disable Automatic Redirection in Requests in Python

Source: https://github.com/psf/requests/blob/main/docs/user/quickstart.rst

This snippet shows how to prevent Requests from automatically following redirects by setting `allow_redirects=False` in a GET request. The response's status code will reflect the initial redirect, and the history will be empty.

```python
r = requests.get('http://github.com/', allow_redirects=False)

r.status_code
301

r.history
[]
```

--------------------------------

### Print the URL with automatically encoded query parameters in Python Requests

Source: https://github.com/psf/requests/blob/main/docs/user/quickstart.rst

After making a request with parameters, this snippet shows how to access and print the complete, URL-encoded URL from the `Response` object `r`, verifying the parameter encoding.

```python
print(r.url)
```

--------------------------------

### Streaming Large File Downloads to Disk with Python Requests

Source: https://github.com/psf/requests/blob/main/docs/user/quickstart.rst

Shows the recommended way to stream and save content to a file using `Response.iter_content()`. This method handles decoding of transfer-encodings (like gzip/deflate) and allows for chunked writing to prevent large memory consumption when downloading big files.

```python
with open(filename, 'wb') as fd:
    for chunk in r.iter_content(chunk_size=128):
        fd.write(chunk)
```

--------------------------------

### Check HTTP Response Status Code with Requests in Python

Source: https://github.com/psf/requests/blob/main/docs/user/quickstart.rst

Shows how to retrieve the HTTP status code from a 'requests.Response' object after making a request. The 'status_code' attribute provides the numeric status code.

```python
r = requests.get('https://httpbin.org/get')
r.status_code
```

--------------------------------

### Access HTTP Response Headers with Requests in Python

Source: https://github.com/psf/requests/blob/main/docs/user/quickstart.rst

Shows how to access all HTTP response headers from a 'requests.Response' object. The 'headers' attribute returns a dictionary-like object representing the server's response headers.

```python
r.headers
```

--------------------------------

### Accessing Raw HTTP Response Stream with Python Requests

Source: https://github.com/psf/requests/blob/main/docs/user/quickstart.rst

Illustrates how to access the raw socket response using `r.raw` after setting `stream=True` in the initial `requests.get()` call. This provides direct byte access to the underlying `urllib3` response object for low-level processing.

```python
r = requests.get('https://api.github.com/events', stream=True)
r.raw
r.raw.read(10)
```

--------------------------------

### Download Requests source tarball using curl

Source: https://github.com/psf/requests/blob/main/docs/user/install.rst

This command downloads the latest stable source code of the Requests library as a tarball archive from GitHub using the curl utility. This is an alternative to cloning for obtaining a snapshot of the source.

```shell
curl -OL https://github.com/psf/requests/tarball/main
```

--------------------------------

### Upload String Content as a File Multipart-Encoded with Requests in Python

Source: https://github.com/psf/requests/blob/main/docs/user/quickstart.rst

Demonstrates sending a string directly as file content in a multipart/form-data request. The 'files' parameter can take a tuple (filename, string_content) to treat the string as a file for upload purposes.

```python
url = 'https://httpbin.org/post'
files = {'file': ('report.csv', 'some,data,to,send\nanother,row,to,send\n')}

r = requests.post(url, files=files)
```

--------------------------------

### Sending Form-Encoded Data in Python Requests POST

Source: https://github.com/psf/requests/blob/main/docs/user/quickstart.rst

Demonstrates sending form-encoded data in a POST request by passing a dictionary to the `data` parameter. The dictionary is automatically encoded into `application/x-www-form-urlencoded` format, mimicking an HTML form submission.

```python
payload = {'key1': 'value1', 'key2': 'value2'}
r = requests.post('https://httpbin.org/post', data=payload)
print(r.text)
```

--------------------------------

### Upload File with Custom Metadata Multipart-Encoded with Requests in Python

Source: https://github.com/psf/requests/blob/main/docs/user/quickstart.rst

Explains how to upload a file while explicitly setting its filename, content type, and headers. The 'files' parameter accepts a tuple in the format (filename, file_object, content_type, headers) for more granular control over the uploaded file's metadata.

```python
url = 'https://httpbin.org/post'
files = {'file': ('report.xls', open('report.xls', 'rb'), 'application/vnd.ms-excel', {'Expires': '0'})}

r = requests.post(url, files=files)
```

--------------------------------

### Set Request Timeout in Python Requests

Source: https://github.com/psf/requests/blob/main/docs/user/quickstart.rst

This snippet illustrates how to set a timeout for a request using the `timeout` parameter. A `requests.exceptions.Timeout` exception is raised if no bytes are received on the underlying socket within the specified duration.

```python
requests.get('https://github.com/', timeout=0.001)
```

--------------------------------

### Adding Custom HTTP Headers to Python Requests

Source: https://github.com/psf/requests/blob/main/docs/user/quickstart.rst

Explains how to include custom HTTP headers in a Requests call by passing a dictionary to the `headers` parameter. It specifies that header values must be strings and outlines precedence rules for custom headers against other authentication methods.

```python
url = 'https://api.github.com/some/endpoint'
headers = {'user-agent': 'my-app/0.0.1'}
r = requests.get(url, headers=headers)
```

--------------------------------

### Pass URL query parameters using a dictionary in Python Requests

Source: https://github.com/psf/requests/blob/main/docs/user/quickstart.rst

This snippet demonstrates how to include query string parameters in a URL by providing a Python dictionary to the `params` argument of `requests.get()`. The library automatically handles URL encoding for the key-value pairs.

```python
payload = {'key1': 'value1', 'key2': 'value2'}
r = requests.get('https://httpbin.org/get', params=payload)
```

--------------------------------

### Raise HTTPError for Bad Status Codes with Requests in Python

Source: https://github.com/psf/requests/blob/main/docs/user/quickstart.rst

Explains how to use 'Response.raise_for_status()' to automatically raise an 'requests.exceptions.HTTPError' if the request was unsuccessful (4XX client error or 5XX server error). If the status code is 2XX, it returns None.

```python
bad_r = requests.get('https://httpbin.org/status/404')
bad_r.status_code
bad_r.raise_for_status()
r.raise_for_status()
```

--------------------------------

### Upload Single File Multipart-Encoded with Requests in Python

Source: https://github.com/psf/requests/blob/main/docs/user/quickstart.rst

Shows how to upload a single file using a multipart/form-data request. The 'files' parameter expects a dictionary where keys are field names and values are file-like objects opened in binary mode. It is strongly recommended to open files in binary mode to ensure correct Content-Length calculation.

```python
url = 'https://httpbin.org/post'
files = {'file': open('report.xls', 'rb')}

r = requests.post(url, files=files)
```

--------------------------------

### Sending Multiple Values for Form Keys in Python Requests POST

Source: https://github.com/psf/requests/blob/main/docs/user/quickstart.rst

Illustrates how to send multiple values for the same key in form-encoded POST data. This can be achieved by providing the `data` parameter as a list of tuples or a dictionary where the values are lists, accommodating forms with repeated fields.

```python
payload_tuples = [('key1', 'value1'), ('key1', 'value2')]
r1 = requests.post('https://httpbin.org/post', data=payload_tuples)
payload_dict = {'key1': ['value1', 'value2']}
r2 = requests.post('https://httpbin.org/post', data=payload_dict)
print(r1.text)
r1.text == r2.text
```

--------------------------------

### Inspect and modify HTTP response text encoding in Python Requests

Source: https://github.com/psf/requests/blob/main/docs/user/quickstart.rst

This snippet shows how to check the encoding guessed by Requests using `r.encoding` and how to manually set a different encoding. Changing `r.encoding` affects how subsequent access to `r.text` decodes the response body.

```python
r.encoding
r.encoding = 'ISO-8859-1'
```

--------------------------------

### POST JSON Data Manually with Requests in Python

Source: https://github.com/psf/requests/blob/main/docs/user/quickstart.rst

Demonstrates how to send JSON-encoded data in a POST request by manually serializing a Python dictionary to a JSON string and passing it to the 'data' parameter. This method does not automatically set the 'Content-Type' header to 'application/json'.

```python
import json

url = 'https://api.github.com/some/endpoint'
payload = {'some': 'data'}

r = requests.post(url, data=json.dumps(payload))
```

--------------------------------

### Perform an HTTP GET Request to GitHub API with Requests

Source: https://github.com/psf/requests/blob/main/docs/user/advanced.rst

Demonstrates how to make a basic HTTP GET request to a URL using the `requests` library in Python. This example fetches specific commit information from the GitHub API using a commit hash.

```python
import requests
r = requests.get('https://api.github.com/repos/psf/requests/git/commits/a050faf084662f3a352dd1a941f2c7c9f886d4ad')
```

--------------------------------

### Parsing JSON Response with Python Requests

Source: https://github.com/psf/requests/blob/main/docs/user/quickstart.rst

Demonstrates how to parse a JSON response body from a Requests Response object using the `r.json()` method. It notes that `requests.exceptions.JSONDecodeError` is raised on failure and that a successful JSON parse does not imply a successful HTTP status.

```python
r.json()
```

--------------------------------

### Pass list values as URL query parameters in Python Requests

Source: https://github.com/psf/requests/blob/main/docs/user/quickstart.rst

This snippet illustrates how to handle cases where a single query parameter has multiple values. By providing a list as a dictionary value to the `params` argument, Requests generates multiple key-value pairs in the URL's query string.

```python
payload = {'key1': 'value1', 'key2': ['value2', 'value3']}

r = requests.get('https://httpbin.org/get', params=payload)
print(r.url)
```

--------------------------------

### POST JSON Data Automatically with Requests in Python

Source: https://github.com/psf/requests/blob/main/docs/user/quickstart.rst

Illustrates a simpler way to send JSON-encoded data using the 'json' parameter (available since Requests 2.4.2). This method automatically serializes the dictionary to JSON and sets the 'Content-Type' header to 'application/json'. It is ignored if 'data' or 'files' parameters are also passed.

```python
url = 'https://api.github.com/some/endpoint'
payload = {'some': 'data'}

r = requests.post(url, json=payload)
```

--------------------------------

### Access HTTP response body as decoded text in Python Requests

Source: https://github.com/psf/requests/blob/main/docs/user/quickstart.rst

This snippet demonstrates how to retrieve the body of an HTTP response as a Unicode string using the `r.text` attribute. Requests automatically decodes the content, making an educated guess about the encoding based on HTTP headers.

```python
import requests

r = requests.get('https://api.github.com/events')
r.text
```

--------------------------------

### Install Requests with chardet for Python 3

Source: https://github.com/psf/requests/blob/main/HISTORY.md

This command demonstrates how to install the Requests library using pip, specifically including the `chardet` dependency for Python 3 environments. This option ensures backwards compatibility or explicit `chardet` usage if `charset_normalizer` is not preferred.

```shell
pip install "requests[use_chardet_on_py3]"
```

--------------------------------

### Discover Allowed HTTP Methods with OPTIONS Verb using Requests

Source: https://github.com/psf/requests/blob/main/docs/user/advanced.rst

Demonstrates how a correctly implemented HTTP OPTIONS verb would return supported methods in the 'Allow' header of the response. This example queries a hypothetical API endpoint to show the expected output, listing methods like GET, HEAD, POST, and OPTIONS.

```python
verbs = requests.options('http://a-good-website.com/api/cats')
print(verbs.headers['allow'])
```

--------------------------------

### Access HTTP response body as raw binary bytes in Python Requests

Source: https://github.com/psf/requests/blob/main/docs/user/quickstart.rst

This snippet illustrates how to retrieve the raw HTTP response body as a byte string using the `r.content` attribute. This is suitable for non-textual data like images, and common transfer-encodings (gzip, deflate, br) are automatically decoded.

```python
r.content
```

--------------------------------

### Install Requests SOCKS Proxy Dependencies

Source: https://github.com/psf/requests/blob/main/docs/user/advanced.rst

This bash command installs the necessary third-party libraries for enabling SOCKS proxy support in the `requests` library. It uses `pip` to install the 'socks' extra.

```bash
python -m pip install 'requests[socks]'
```

--------------------------------

### Install Python Requests Library with pip

Source: https://github.com/psf/requests/blob/main/README.md

This console command installs the `requests` HTTP library for Python using `pip`, the standard package installer. It ensures the library is available for use in Python projects, enabling easy HTTP request handling.

```console
$ python -m pip install requests
```

--------------------------------

### Configure Scheme-Host Specific Proxy in Python

Source: https://github.com/psf/requests/blob/main/docs/user/advanced.rst

This Python example demonstrates how to define a proxy that applies only to a specific scheme and exact hostname. The key in the `proxies` dictionary uses the format `scheme://hostname`.

```python
proxies = {'http://10.20.1.128': 'http://10.10.1.10:5323'}
```

--------------------------------

### Perform a Basic GET Request and Process Response with Python Requests

Source: https://github.com/psf/requests/blob/main/docs/index.rst

This snippet demonstrates how to send a basic GET request to an API endpoint using the 'requests' library in Python. It illustrates accessing the HTTP status code, response headers, content encoding, raw text body, and parsing JSON data from the API's response.

```python
r = requests.get('https://api.github.com/user', auth=('user', 'pass'))
r.status_code
200
r.headers['content-type']
'application/json; charset=utf8'
r.encoding
'utf-8'
r.text
'{"type":"User"...'
r.json()
{'private_gists': 419, 'total_private_repos': 77, ...}
```

--------------------------------

### Configure Proxies for a Requests Session in Python

Source: https://github.com/psf/requests/blob/main/docs/user/advanced.rst

This Python example shows how to configure proxies for an entire `requests.Session` object. A proxy dictionary is updated on `session.proxies`, ensuring all subsequent requests made with that session use the specified proxies.

```python
import requests

proxies = {
  'http': 'http://10.10.1.10:3128',
  'https': 'http://10.10.1.10:1080',
}
session = requests.Session()
session.proxies.update(proxies)

session.get('http://example.org')
```

--------------------------------

### Configure Proxies with Scheme in Requests 2.x

Source: https://github.com/psf/requests/blob/main/docs/api.rst

This Python example demonstrates the updated proxy configuration in Requests 2.x, where the scheme for a proxy URL is now explicitly required. In earlier versions, omitting the scheme for a proxy might have been tolerated, but 2.x will raise a `requests.exceptions.MissingSchema` error if it's not provided.

```python
proxies = {
  "http": "10.10.1.10:3128"    # use http://10.10.1.10:3128 instead
}

# In requests 1.x, this was legal, in requests 2.x,
#  this raises requests.exceptions.MissingSchema
requests.get("http://example.org", proxies=proxies)
```

--------------------------------

### Enable HTTP debugging for Requests library

Source: https://github.com/psf/requests/blob/main/docs/api.rst

Provides a Python example for enabling detailed debugging output for the Requests library, specifically at the `http.client` level. This configuration allows logging HTTP requests and responses (headers but not body data), useful for troubleshooting network interactions.

```python
import requests
import logging

# Enabling debugging at http.client level (requests->urllib3->http.client)
# you will see the REQUEST, including HEADERS and DATA, and RESPONSE with HEADERS but without DATA.
# the only thing missing will be the response.body which is not logged.
try: # for Python 3
    from http.client import HTTPConnection
except ImportError:
    from httplib import HTTPConnection
HTTPConnection.debuglevel = 1

logging.basicConfig() # you need to initialize logging, otherwise you will not see anything from requests
logging.getLogger().setLevel(logging.DEBUG)
requests_log = logging.getLogger("urllib3")
requests_log.setLevel(logging.DEBUG)
requests_log.propagate = True

requests.get('https://httpbin.org/headers')
```

--------------------------------

### Perform Authenticated GET Request using Python Requests

Source: https://github.com/psf/requests/blob/main/README.md

This Python code demonstrates making an authenticated GET request to an HTTP endpoint using the `requests` library. It includes passing username and password for basic authentication and then accessing various properties of the response object, such as status code, headers, encoding, and parsing the JSON content.

```python
>>> import requests
>>> r = requests.get('https://httpbin.org/basic-auth/user/pass', auth=('user', 'pass'))
>>> r.status_code
200
>>> r.headers['content-type']
'application/json; charset=utf8'
>>> r.encoding
'utf-8'
>>> r.text
'{"authenticated": true, ...'
>>> r.json()
{'authenticated': True, ...}
```

--------------------------------

### Set Separate Connect and Read Timeouts with Python Requests

Source: https://github.com/psf/requests/blob/main/docs/user/advanced.rst

This example shows how to configure distinct timeout values for the connection and read phases of an HTTP request. A tuple `(connect_timeout, read_timeout)` is passed to the `timeout` parameter, allowing granular control over each stage.

```python
r = requests.get('https://github.com', timeout=(3.05, 27))
```

--------------------------------

### Set Combined Connect and Read Timeout with Python Requests

Source: https://github.com/psf/requests/blob/main/docs/user/advanced.rst

This example demonstrates setting a single timeout value for both the connection establishment and the server response read using the `requests.get` method. The specified duration applies to both phases of the request.

```python
r = requests.get('https://github.com', timeout=5)
```

--------------------------------

### Deferring Response Body Download with Requests stream=True (Python)

Source: https://github.com/psf/requests/blob/main/docs/user/advanced.rst

This snippet demonstrates how to initiate an HTTP GET request using the `requests` library in Python, deferring the download of the response body. By setting `stream=True`, only the response headers are downloaded initially, keeping the connection open until `Response.content` is accessed or the connection is explicitly closed. This is useful for handling large files or making content retrieval conditional.

```python
tarball_url = 'https://github.com/psf/requests/tarball/main'
r = requests.get(tarball_url, stream=True)
```

--------------------------------

### Retrieve Specific GitHub Issue Details using Requests

Source: https://github.com/psf/requests/blob/main/docs/user/advanced.rst

Fetches details for a specific GitHub issue using a GET request to the GitHub API. It then loads the response text into a JSON object (assuming `json` module is imported) to extract and print the issue's title and the total number of comments.

```python
r = requests.get('https://api.github.com/repos/psf/requests/issues/482')
r.status_code

issue = json.loads(r.text)

print(issue['title'])

print(issue['comments'])
```

--------------------------------

### Attempt to Use HTTP OPTIONS Verb with Requests (GitHub API Example)

Source: https://github.com/psf/requests/blob/main/docs/user/advanced.rst

This snippet attempts to use the HTTP OPTIONS verb on the GitHub API to discover supported methods for a given URL. In this particular case, GitHub's API returns a 500 status code, indicating that it does not implement the OPTIONS method for this endpoint.

```python
verbs = requests.options(r.url)
verbs.status_code
```

--------------------------------

### Retrieve Response Headers from Requests Object (Python)

Source: https://github.com/psf/requests/blob/main/docs/user/advanced.rst

This code demonstrates how to make a GET request using the `requests` library and then access the HTTP headers returned by the server. The `r.headers` attribute provides a dictionary-like object containing all response headers.

```python
r = requests.get('https://en.wikipedia.org/wiki/Monty_Python')
r.headers
```

--------------------------------

### Understand Non-Persistent Method-Level Parameters in Requests Session (Python)

Source: https://github.com/psf/requests/blob/main/docs/user/advanced.rst

This example highlights that parameters passed directly to a request method (e.g., `cookies` in `s.get()`) are not persisted by the session for subsequent requests. It demonstrates that such parameters are ephemeral and only apply to the specific call they are provided to.

```python
s = requests.Session()

r = s.get('https://httpbin.org/cookies', cookies={'from-my': 'browser'})
print(r.text)
# '{"cookies": {"from-my": "browser"}}'

r = s.get('https://httpbin.org/cookies')
print(r.text)
# '{"cookies": {}}'
```

--------------------------------

### Configure SOCKS Proxies for Requests in Python

Source: https://github.com/psf/requests/blob/main/docs/user/advanced.rst

This Python snippet demonstrates how to configure SOCKS proxies for `requests` using the `socks5` scheme in the proxy URL. This setup supports SOCKSv5 proxies for both HTTP and HTTPS requests.

```python
proxies = {
    'http': 'socks5://user:pass@host:port',
    'https': 'socks5://user:pass@host:port'
}
```

--------------------------------

### Mount a Custom Transport Adapter in Requests Session (Python)

Source: https://github.com/psf/requests/blob/main/docs/user/advanced.rst

This snippet demonstrates how to register a custom `Transport Adapter` instance to a specific URL prefix within a `requests.Session`. Once mounted, any subsequent HTTP request made through that session, whose URL starts with the specified prefix, will utilize the custom adapter's logic.

```python
s.mount('https://github.com/', MyAdapter())
```

--------------------------------

### Send Authenticated POST Request with Basic Auth in Python

Source: https://github.com/psf/requests/blob/main/docs/user/advanced.rst

This example shows how to successfully make an authenticated POST request to an API using HTTP Basic Authentication with the `requests` library. It includes importing `HTTPBasicAuth`, creating an authentication object, and verifying the successful 201 status code and response content.

```python
>>> from requests.auth import HTTPBasicAuth
>>> auth = HTTPBasicAuth('fake@example.com', 'not_a_real_password')

>>> r = requests.post(url=url, data=body, auth=auth)
>>> r.status_code
201

>>> content = r.json()
>>> print(content['body'])
Sounds great! I'll get right on it.
```

--------------------------------

### Configure Automatic Retries for Requests Session (Python)

Source: https://github.com/psf/requests/blob/main/docs/user/advanced.rst

This example shows how to implement automatic retries for HTTP requests within a `requests.Session` using `urllib3.util.Retry`. It configures retry attempts, backoff factor, and specifies which HTTP status codes and methods should trigger a retry, then applies these settings via an `HTTPAdapter` mounted to the session.

```python
from urllib3.util import Retry
from requests import Session
from requests.adapters import HTTPAdapter

s = Session()
retries = Retry(
    total=3,
    backoff_factor=0.1,
    status_forcelist=[502, 503, 504],
    allowed_methods={'POST'},
)
s.mount('https://', HTTPAdapter(max_retries=retries))
```

--------------------------------

### Persist Cookies Using Requests Session Object (Python)

Source: https://github.com/psf/requests/blob/main/docs/user/advanced.rst

This example demonstrates how to use a `requests.Session` object to automatically persist cookies across multiple HTTP requests. It sets a cookie in the first request and verifies its persistence in a subsequent request, showing how the session handles cookie management.

```python
s = requests.Session()

s.get('https://httpbin.org/cookies/set/sessioncookie/123456789')
r = s.get('https://httpbin.org/cookies')

print(r.text)
# '{"cookies": {"sessioncookie": "123456789"}}'
```

--------------------------------

### Set Indefinite Timeout for HTTP Requests with Python Requests

Source: https://github.com/psf/requests/blob/main/docs/user/advanced.rst

This example illustrates how to disable timeouts, instructing the `requests` library to wait indefinitely for a response from the server. Passing `None` to the `timeout` parameter removes any time limit.

```python
r = requests.get('https://github.com', timeout=None)
```

--------------------------------

### Apply Custom Authentication to Python Requests

Source: https://github.com/psf/requests/blob/main/docs/user/advanced.rst

Demonstrates how to use a custom authentication class, `PizzaAuth`, with a `requests` GET request. An instance of `PizzaAuth` is passed to the `auth` parameter, which then modifies the outgoing request by adding the custom authentication header before it is dispatched. This enables the use of bespoke authentication methods with the `requests` library.

```python
requests.get('http://pizzabin.org/admin', auth=PizzaAuth('kenneth'))
```

--------------------------------

### Sending Chunk-Encoded Requests with a Generator in Requests (Python)

Source: https://github.com/psf/requests/blob/main/docs/user/advanced.rst

This example demonstrates how to send a chunk-encoded HTTP POST request using the `requests` library in Python. A generator function `gen()` is used to yield parts of the request body, which `requests` then sends as chunks. This is useful for dynamically generated content or when the total size of the body is not known beforehand.

```python
def gen():
    yield 'hi'
    yield 'there'

requests.post('http://some.url/chunked', data=gen())
```

--------------------------------

### Perform Successful Default SSL Certificate Verification in Python Requests

Source: https://github.com/psf/requests/blob/main/docs/user/advanced.rst

Shows a successful `GET` request to an HTTPS URL where Requests' default SSL certificate verification passes. This indicates that the server's certificate is trusted and valid.

```python
>>> requests.get('https://github.com')
<Response [200]>
```

--------------------------------

### Retrieve Requests Default CA Bundle Path in Python

Source: https://github.com/psf/requests/blob/main/docs/user/advanced.rst

This Python snippet shows how to programmatically get the file path to the default Certificate Authority (CA) bundle used by the `requests` library. This path indicates where `requests` looks for trusted root certificates by default.

```python
from requests.utils import DEFAULT_CA_BUNDLE_PATH
print(DEFAULT_CA_BUNDLE_PATH)
```

--------------------------------

### Iterate Requests Response Lines Safely in Python

Source: https://github.com/psf/requests/blob/main/docs/user/advanced.rst

This Python example shows a reentrant-safe way to iterate over lines from a `requests.Response` object. By explicitly creating an iterator and using `next()` to consume initial lines, it prevents data loss that can occur when calling `iter_lines()` multiple times on the same response object.

```python
lines = r.iter_lines()
# Save the first line for later or just skip it

first_line = next(lines)

for line in lines:
    print(line)
```

--------------------------------

### Delete API Resource with Authenticated DELETE Request in Python

Source: https://github.com/psf/requests/blob/main/docs/user/advanced.rst

This snippet demonstrates sending an authenticated DELETE request to remove a specific resource from an API, using a GitHub comment as an example. It shows checking for a 204 No Content status code upon successful deletion.

```python
>>> r = requests.delete(url=url, auth=auth)
>>> r.status_code
204
>>> r.headers['status']
'204 No Content'
```

--------------------------------

### Initialize BuySellAds Native Ribbon Ad

Source: https://github.com/psf/requests/blob/main/docs/_templates/hacks.html

This JavaScript snippet initializes the BuySellAds (BSA) platform to display a native sponsored ad ribbon. It targets a specific HTML element ('#native-ribbon') and defines a comprehensive custom template for the ad, including inline styling for various ad components like background gradients, text colors, and call-to-action button appearance.

```javascript
_bsa.init('custom', 'CK7D62JU', 'placement:pythonrequestsorg', { target: '#native-ribbon', template: '\n <div class="native-sponsor">Sponsored by ##company## — Learn More</div>\n <a href="##link##" class="native-flex">\n <style>\n #native-ribbon #_custom_ { background: linear-gradient(-30deg, ##backgroundColor##E5, ##backgroundColor##E5 45%, ##backgroundColor## 45%) #fff; }\n .native-details, .native-sponsor, .native-bsa { color: ##textColor## !important; }\n .native-details:hover { color: ##textColorHover## !important; }\n .native-cta { color: ##ctaTextColor##; background-color: ##ctaBackgroundColor##; }\n .native-cta:hover { color: ##ctaTextColorHover##; background-color: ##ctaBackgroundColorHover##; }\n </style>\n <div class="native-main">\n <img class="native-img" src="##logo##">\n <div class="native-details">\n <span class="native-company">##title##</span>\n <span class="native-desc">##description##</span>\n </div>\n </div>\n <span class="native-cta">##callToAction##</span>\n </a>\n </div>\n' } );
```

--------------------------------

### Perform Basic Authentication with requests.auth.HTTPBasicAuth in Python

Source: https://github.com/psf/requests/blob/main/docs/user/authentication.rst

Demonstrates how to use HTTP Basic Authentication with the Requests library by explicitly importing `HTTPBasicAuth` and passing an instance with username and password to the `auth` parameter.

```python
from requests.auth import HTTPBasicAuth
basic = HTTPBasicAuth('user', 'pass')
requests.get('https://httpbin.org/basic-auth/user/pass', auth=basic)
```

--------------------------------

### Manually Prepare a Request for Advanced Customization (Python)

Source: https://github.com/psf/requests/blob/main/docs/user/advanced.rst

This code demonstrates how to manually construct and prepare a `Request` object using `requests.Request` and `req.prepare()`. This advanced technique allows for inspection and modification of the request's body, headers, or other attributes *before* sending it, offering fine-grained control.

```python
from requests import Request, Session

s = Session()

req = Request('POST', url, data=data, headers=headers)
prepped = req.prepare()

# do something with prepped.body
```

--------------------------------

### Configure Requests Proxies Using Environment Variables

Source: https://github.com/psf/requests/blob/main/docs/user/advanced.rst

This snippet demonstrates how to set up HTTP, HTTPS, and SOCKS proxies using environment variables (`HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`). Requests automatically detects and uses these variables for proxy configuration when making requests.

```bash
export HTTP_PROXY="http://10.10.1.10:3128"
export HTTPS_PROXY="http://10.10.1.10:1080"
export ALL_PROXY="socks5://10.10.1.10:3434"
```

```python
import requests
requests.get('http://example.org')
```

--------------------------------

### Apply Custom CSS Styles for Documentation Layout

Source: https://github.com/psf/requests/blob/main/docs/_templates/hacks.html

This CSS block applies various styling adjustments to a documentation site, likely built with Sphinx. It includes rules for logo alignment, search box capitalization, document width, code block padding, and responsive design for smaller screens, hiding the sidebar and adjusting document width to ensure content remains readable.

```css
/* Rezzy requires precise alignment. */ img.logo {margin-left: -20px!important;} /* "Quick Search" should be capitalized. */ div#searchbox h3 {text-transform: capitalize;} /* Make the document a little wider, less code is cut-off. */ div.document {width: 1008px;} /* Much-improved spacing around code blocks. */ div.highlight pre {padding: 11px 14px;} /* Remain Responsive! */ @media screen and (max-width: 1008px) { div.sphinxsidebar {display: none;} div.document {width: 100%!important;} /* Have code blocks escape the document right-margin. */ div.highlight pre {margin-right: -30px;} }
```

--------------------------------

### Prepare and Send a Request Using a Python Requests Session

Source: https://github.com/psf/requests/blob/main/docs/user/advanced.rst

Shows how to use `Session.prepare_request()` to prepare a `Request` object. This method ensures that `Session`-level state, such as cookies, is applied to the request before modifications and sending. It's the recommended way to use `PreparedRequest` with Sessions.

```python
from requests import Request, Session

s = Session()
req = Request('GET',  url, data=data, headers=headers)

prepped = s.prepare_request(req)

# do something with prepped.body
prepped.body = 'Seriously, send exactly these bytes.'

# do something with prepped.headers
prepped.headers['Keep-Dead'] = 'parrot'

resp = s.send(prepped,
    stream=stream,
    verify=verify,
    proxies=proxies,
    cert=cert,
    timeout=timeout
)

print(resp.status_code)
```

--------------------------------

### Initialize Requests Session Object in Python

Source: https://github.com/psf/requests/blob/main/docs/user/advanced.rst

Illustrates the basic initialization of a `requests.Session` object. Sessions allow for persistence of parameters across multiple requests, such as cookies, authentication, and headers, improving efficiency and state management.

```python
>>> s = requests.Session()
```

--------------------------------

### Recommended Direct urllib3 Import Style

Source: https://github.com/psf/requests/blob/main/HISTORY.md

The recommended approach post-2.16.1 for importing vendored libraries like `urllib3` is to import them directly, bypassing the `requests.packages` namespace entirely. This Python code illustrates the preferred import path for `PoolManager`.

```python
from urllib3.poolmanager import PoolManager
```

--------------------------------

### Merge Environment Settings for PreparedRequest in Python Requests

Source: https://github.com/psf/requests/blob/main/docs/user/advanced.rst

Illustrates how to explicitly merge environment settings (e.g., `REQUESTS_CA_BUNDLE` for SSL certs) into a `Session`-prepared request. This is necessary because `PreparedRequest` objects do not automatically consider environment variables, preventing `SSLError` exceptions for self-signed certificates.

```python
from requests import Request, Session

s = Session()
req = Request('GET', url)

prepped = s.prepare_request(req)

# Merge environment settings into session
settings = s.merge_environment_settings(prepped.url, {}, None, None, None)
resp = s.send(prepped, **settings)

print(resp.status_code)
```

--------------------------------

### Initialize a Session object in Requests 1.x

Source: https://github.com/psf/requests/blob/main/docs/api.rst

Shows how to initialize and configure a `requests.Session` object in Requests 1.x. Sessions no longer take parameters directly during instantiation; configuration like authentication and headers are set on the session object afterwards.

```python
s = requests.Session()    # formerly, session took parameters
s.auth = auth
s.headers.update(headers)
r = s.get('https://httpbin.org/headers')
```

--------------------------------

### Configure Proxies with Basic Authentication

Source: https://github.com/psf/requests/blob/main/docs/user/advanced.rst

This snippet shows how to include HTTP Basic Authentication credentials directly in proxy URLs. It covers both setting proxies via the `HTTPS_PROXY` environment variable in bash and defining them in a Python dictionary for `requests`.

```bash
export HTTPS_PROXY="http://user:pass@10.10.1.10:1080"
```

```python
proxies = {'http': 'http://user:pass@10.10.1.10:3128/'}
```

--------------------------------

### Configure Proxies for a Single Request in Python

Source: https://github.com/psf/requests/blob/main/docs/user/advanced.rst

This Python snippet demonstrates how to set up HTTP and HTTPS proxies for a single `requests` call. A dictionary mapping schemes to proxy URLs is passed directly to the `proxies` argument of `requests.get()`.

```python
import requests

proxies = {
  'http': 'http://10.10.1.10:3128',
  'https': 'http://10.10.1.10:1080',
}

requests.get('http://example.org', proxies=proxies)
```

--------------------------------

### Perform Basic Authentication using a tuple shorthand in Python Requests

Source: https://github.com/psf/requests/blob/main/docs/user/authentication.rst

Illustrates a convenient shorthand for HTTP Basic Authentication in the Requests library. By passing a tuple of `(username, password)` directly to the `auth` parameter, Requests automatically handles basic authentication.

```python
requests.get('https://httpbin.org/basic-auth/user/pass', auth=('user', 'pass'))
```