Requests

https://github.com/psf/requests
Admin
Requests is a simple, elegant, and widely-used Python HTTP library that makes sending HTTP requests...
Tokens:65,465
Snippets:573
Trust Score:7.3
License:Apache-2.0
Update:1 day ago
Show doc for...
Tokens:
Raw
### Install Requests from local source

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

Navigates into the source directory and installs the package into site-packages.

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

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

### Install SOCKS proxy dependencies

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

Install optional dependencies required for SOCKS proxy support in Requests using pip.

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

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

### Installing Requests via pip

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

Install the official Requests package from PyPI. Requests officially supports Python 3.10+.

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

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

### Install Requests via pip

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

Installs the Requests package into your Python environment using pip.

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

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

### Install Requests with use_chardet_on_py3 Extra

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

Installs the Requests package while specifying the `use_chardet_on_py3` extra to use `chardet` instead of `charset_normalizer` on Python 3. Python 2 environments still depend upon `chardet` by default.

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

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

### Make an HTTP GET request

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

Performs a simple GET request and returns a Response object containing the response data.

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

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

### Making an Authenticated GET Request with requests.get

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

Send an authenticated HTTP GET request and inspect response attributes such as status code, headers, encoding, text, and JSON body.

```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, ...}
```

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

### Disable redirection with allow_redirects=False

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

Disable automatic redirect handling for verbs like GET, POST, or DELETE by passing allow_redirects=False.

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

>>> r.status_code
301

>>> r.history
[]
```

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

### Implement custom authentication with AuthBase

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

Subclass requests.auth.AuthBase and implement the __call__() method to define custom authentication logic. The handler is invoked during request setup and can modify the request before sending.

```python
>>> import requests
>>> class MyAuth(requests.auth.AuthBase):
...     def __call__(self, r):
...         # Implement my authentication
...         return r
...
>>> url = 'https://httpbin.org/get'
>>> requests.get(url, auth=MyAuth())
<Response [200]>
```

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

### Access case-insensitive headers by key

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

Access HTTP response headers using any letter casing via dictionary indexing or the get() method.

```python
>>> r.headers['Content-Type']
'application/json'

>>> r.headers.get('content-type')
'application/json'
```

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

### Make PUT, DELETE, HEAD, and OPTIONS requests

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

Demonstrates executing other standard HTTP methods using Requests.

```python
>>> 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')
```

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

### Configure HTTP Basic Auth with a proxy

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

Use the http://user:password@host/ format in environment variables or dictionary configurations to authenticate with a proxy.

```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 via environment variables

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

Set standard environment variables like HTTP_PROXY, HTTPS_PROXY, or ALL_PROXY to configure Requests automatically when proxies are not explicitly overridden.

```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')
```

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

### Specify Client Side Certificate as a Tuple of Files

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

Specify a local certificate to use as a client-side certificate with a tuple containing both the certificate and private key file paths.

```python
>>> requests.get('https://kennethreitz.org', cert=('/path/client.cert', '/path/client.key'))
<Response [200]>
```

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

### Instantiate Session and configure headers and auth

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

Session objects in Requests 1.x no longer accept parameters during instantiation. Configure authentication and headers directly on the session instance before sending requests.

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

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

### Import PoolManager directly from urllib3

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

Recommended import approach directly referencing the top-level urllib3 package.

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

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

### Configure proxy for a specific scheme and host

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

Specify the scheme://hostname format as the dictionary key to match requests targeted only to that exact scheme and hostname.

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

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

### Perform Successful SSL Verification

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

Demonstrates successful default SSL verification against a domain with valid TLS certificates.

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

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

### Use Session as a context manager

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

Wraps a session in a `with` block to ensure the session is automatically closed upon exit, even if exceptions occur.

```python
with requests.Session() as s:
    s.get('https://httpbin.org/cookies/set/sessioncookie/123456789')
```

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

### Create an image from binary response content

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

Use PIL and BytesIO to create an image object directly from binary data returned in r.content.

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

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

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

### Authenticate with HTTP Basic Auth tuple shorthand

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

Pass username and password as a tuple shorthand directly into the auth parameter instead of creating an HTTPBasicAuth object.

```python
>>> requests.get('https://httpbin.org/basic-auth/user/pass', auth=('user', 'pass'))
<Response [200]>
```

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

### Prepare and modify a Request with Request.prepare()

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

Construct and modify a PreparedRequest directly using req.prepare() before sending it through a Session. Note that Session-level state like cookies will not be applied to the request with this approach.

```python
from requests import Request, Session

s = Session()

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

# do something with prepped.body
prepped.body = 'No, I want exactly this as the body.'

# do something with prepped.headers
del prepped.headers['Content-Type']

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

print(resp.status_code)
```

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

### Configure proxies for individual requests

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

Pass a dictionary of proxy URLs mapped by protocol to the proxies argument on any request method.

```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)
```

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

### Persist cookies across requests with Session

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

Demonstrates setting a cookie and retrieving it across separate requests using a single Session instance.

```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"}}'
```

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

### Mounting a Transport Adapter to a Session

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

Registers a Transport Adapter instance to a URL prefix on a Session. Adapters are chosen based on a longest prefix match, so terminating full hostnames with a slash is recommended.

```python
>>> s = requests.Session()
>>> s.mount('https://github.com/', MyAdapter())
```

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

### Regenerate Test Certificates with Make

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

Regenerates the certificate authority and expired server certificates for test fixtures.

```shell
make clean
make all
```

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

### Prepare a Request with Session state using Session.prepare_request()

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

Use s.prepare_request(req) to obtain a PreparedRequest that retains Session-level state such as cookies. Modify the body or headers on the prepared object before sending with s.send().

```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)
```

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

### Inspect DEFAULT_CA_BUNDLE_PATH

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

Print the default CA bundle path trusted by Requests for verifying HTTPS certificates.

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

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

### Import the Requests module

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

Imports the Requests library before making any HTTP calls.

```python
>>> import requests
```

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

### Enable redirection for HEAD requests with allow_redirects=True

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

Enable location redirection handling for HEAD requests by setting allow_redirects=True, since redirection is disabled for HEAD by default.

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

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

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

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

### Import PoolManager from requests.packages submodule path

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

Legacy import pattern previously used to import PoolManager from the nested requests.packages namespace.

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

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

### Specify Custom CA Bundle with verify Parameter

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

Pass a path to a CA_BUNDLE file or directory with trusted CA certificates. If pointing to a directory, it must be processed using OpenSSL's c_rehash utility.

```python
>>> requests.get('https://github.com', verify='/path/to/certfile')
```

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

### Set default authentication and headers on Session

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

Configures session-level auth and default headers, which are merged with method-level parameters during requests.

```python
s = requests.Session()
s.auth = ('user', 'pass')
s.headers.update({'x-test': 'true'})

# both 'x-test' and 'x-test2' are sent
s.get('https://httpbin.org/headers', headers={'x-test2': 'true'})
```

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

### Merge environment settings into a Prepared Request

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

Merges environment configurations such as REQUESTS_CA_BUNDLE into session settings when using prepared requests. Prevents SSL verification failures caused by environment variables being ignored during prepared request dispatching.

```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)
```

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

### Cloning the Requests Git repository

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

Clone the repository using the -c fetch.fsck.badTimezone=ignore flag to prevent errors related to bad commit timestamps.

```shell
git clone -c fetch.fsck.badTimezone=ignore https://github.com/psf/requests.git
```

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

### Set separate connect and read timeouts with a tuple

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

Sets the connect and read timeouts individually by passing a tuple of (connect, read) seconds.

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

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

### Upload multiple multipart files with requests.post

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

Assign a list of (form_field_name, file_info) tuples to the files parameter to upload multiple files in a single multipart request. Files must be opened in binary mode to avoid Content-Length calculation errors.

```python
>>> url = 'https://httpbin.org/post'
>>> multiple_files = [
...     ('images', ('foo.png', open('foo.png', 'rb'), 'image/png')),
...     ('images', ('bar.png', open('bar.png', 'rb'), 'image/png'))]
>>> r = requests.post(url, files=multiple_files)
>>> r.text
{
  ...
  'files': {'images': 'data:image/png;base64,iVBORw ....'}
  'Content-Type': 'multipart/form-data; boundary=3131623adb2043caaeb5538cc7aa0b3a',
  ...
}
```

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

### Encounter SSLError on Failed Certificate Verification

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

Demonstrates the default behavior when Requests cannot verify a certificate, raising an SSLError on hostname mismatches.

```python
>>> requests.get('https://requestb.in')
requests.exceptions.SSLError: hostname 'requestb.in' doesn't match either of '*.herokuapp.com', 'herokuapp.com'
```

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

### Defer response body download using stream=True

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

Overrides the default behavior of downloading the response body immediately. Keeps the connection open until Response.content is accessed.

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

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

### Configure SOCKS proxy URLs in proxies dictionary

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

Use socks5:// for client-side DNS resolution or socks5h:// to resolve domain names on the SOCKS proxy server.

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

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

### Set Persistent CA Bundle on Session

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

Configure the verify attribute on a Session instance to persist the CA bundle path across multiple requests.

```python
s = requests.Session()
s.verify = '/path/to/certfile'
```

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

### Providing Proxy URL Scheme in Requests 2.x

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

Shows the proxy configuration requirement in Requests 2.x where a URL scheme is mandatory. Supplying a proxy without a scheme raises requests.exceptions.MissingSchema.

```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)
```

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

### Upload a multipart-encoded file using requests.post

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

Uploads a binary file using the files parameter in requests.post. Files should be opened in binary mode ('rb') so that Content-Length is accurately calculated in bytes.

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

>>> r = requests.post(url, files=files)
>>> r.text
{
  ...
  "files": {
    "file": "<censored...binary...data>"
  },
  ...
}
```

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

### Import PoolManager via module-level requests.packages

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

Updated import syntax accessing urllib3 at the module level through requests.packages in version 2.16.1.

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

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

### Make an HTTP POST request with form data

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

Sends an HTTP POST request with key-value data provided in a dictionary.

```python
>>> r = requests.post('https://httpbin.org/post', data={'key': 'value'})
```

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

### Send strings to be received as files in requests.post

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

Uploads string content directly as file data without writing to disk by passing a tuple with the filename and string content.

```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)
>>> r.text
{
  ...
  "files": {
    "file": "some,data,to,send\\nanother,row,to,send\\n"
  },
  ...
}
```

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

### Configuring a Specific SSL Version via HTTPAdapter

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

Subclasses HTTPAdapter and overrides init_poolmanager to pass ssl.PROTOCOL_SSLv3 to urllib3's PoolManager. Use this when connecting to endpoints that require an SSL version incompatible with the default.

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

from requests.adapters import HTTPAdapter


class Ssl3HttpAdapter(HTTPAdapter):
    """"Transport adapter" that allows us to use SSLv3."""

    def init_poolmanager(self, connections, maxsize, block=False):
        self.poolmanager = PoolManager(
            num_pools=connections, maxsize=maxsize,
            block=block, ssl_version=ssl.PROTOCOL_SSLv3)
```

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

### Configure proxies on a Session instance

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

Update session.proxies to set default proxies for all requests made through the Session. Note that values may be overwritten by environmental proxies returned by urllib.request.getproxies.

```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')
```

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

### Set filename, content type, and headers explicitly in requests.post

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

Passes a tuple in the files dictionary to explicitly define the filename, file object, content type, and custom headers for the uploaded file.

```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)
>>> r.text
{
  ...
  "files": {
    "file": "<censored...binary...data>"
  },
  ...
}
```

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

### Enable verbose HTTP debug logging

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

Configures Python logging and HTTPConnection debug levels to log HTTP requests, headers, and response metadata. Note that response bodies are not included in the log output.

```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')
```

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

### Stream large files with requests.post

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

Provide an open file-like object to data to stream files directly without loading them fully into memory. Open files in binary mode ('rb') to ensure the Content-Length header correctly reflects the byte count.

```python
with open('massive-body', 'rb') as f:
    requests.post('http://some.url/streamed', data=f)
```

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

### Retrieve raw Link headers for API pagination

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

Fetches raw Link response headers commonly returned by APIs for pagination.

```python
>>> url = 'https://api.github.com/users/kennethreitz/repos?page=1&per_page=10'
>>> r = requests.head(url=url)
>>> r.headers['link']
'<https://api.github.com/users/kennethreitz/repos?page=2&per_page=10>; rel="next", <https://api.github.com/users/kennethreitz/repos?page=6&per_page=10>; rel="last"'
```

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

### Configuring Git globally to ignore bad timezone errors

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

Set fetch.fsck.badTimezone to ignore in your global Git configuration to avoid timestamp validation errors across all clone operations.

```shell
git config --global fetch.fsck.badTimezone ignore
```

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

### Pass list values in URL query parameters

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

Sends multiple values for a single query parameter key by providing a list in the params dictionary.

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

>>> r = requests.get('https://httpbin.org/get', params=payload)
>>> print(r.url)
https://httpbin.org/get?key1=value1&key2=value2&key2=value3
```

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

### Stream response content with stream=True

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

Use stream=True on request methods to stream responses and read raw content in chunks using iter_content(). This replaces the 0.x prefetch=False option.

```python
# in 0.x, passing prefetch=False would accomplish the same thing
r = requests.get('https://api.github.com/events', stream=True)
for chunk in r.iter_content(8192):
    ...
```

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

### Making OAuth 1 authenticated requests with requests-oauthlib

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

Authenticate requests with OAuth 1 credentials using the OAuth1 helper class from the requests-oauthlib library.

```python
>>> import requests
>>> from requests_oauthlib import OAuth1

>>> url = 'https://api.twitter.com/1.1/account/verify_credentials.json'
>>> auth = OAuth1('YOUR_APP_KEY', 'YOUR_APP_SECRET',
...               'USER_OAUTH_TOKEN', 'USER_OAUTH_TOKEN_SECRET')

>>> requests.get(url, auth=auth)
<Response [200]>
```

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

### Access response headers dictionary

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

View server response headers provided as a specialized dictionary representation.

```python
>>> r.headers
{
    'content-encoding': 'gzip',
    'transfer-encoding': 'chunked',
    'connection': 'close',
    'server': 'nginx/1.0.4',
    'x-runtime': '148ms',
    'etag': '"e1ca502697e5c9317743dc078f67693f"',
    'content-type': 'application/json'
}
```

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

### Authenticate with HTTPBasicAuth object

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

Provide explicit HTTPBasicAuth credentials using the auth argument when making requests.

```python
>>> from requests.auth import HTTPBasicAuth
>>> basic = HTTPBasicAuth('user', 'pass')
>>> requests.get('https://httpbin.org/basic-auth/user/pass', auth=basic)
<Response [200]>
```

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

### Send cookies using a dictionary

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

Send custom cookies to the server by passing a dictionary to the cookies parameter.

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

>>> r = requests.get(url, cookies=cookies)
>>> r.text
'{"cookies": {"cookies_are": "working"}}'
```

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

### Pass URL query parameters using a dictionary

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

Passes query arguments via the params keyword argument and checks the resulting encoded URL. Keys with None values are omitted from the query string.

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

```python
>>> print(r.url)
https://httpbin.org/get?key2=value2&key1=value1
```

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

### Clone Requests source code repository

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

Clones the public Requests repository from GitHub to obtain the source code.

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

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

### Send custom HTTP verbs using requests.request

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

Executes HTTP methods that are not covered by default helper functions, such as the WEBDAV MKCOL method, using the built-in requests.request method.

```python
>>> r = requests.request('MKCOL', url, data=data)
>>> r.status_code
200 # Assuming your call was correct
```

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

### Stream response content to file using iter_content

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

Use Response.iter_content to stream and save response content to a file in chunks. This method automatically decodes gzip and deflate transfer-encodings, and chunk_size can be adjusted to fit your use case.

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

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

### Download Requests source tarball with curl

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

Downloads the main branch source tarball from GitHub using curl. A zipball is also available for Windows users.

```shell
$ curl -OL https://github.com/psf/requests/tarball/main
# optionally, zipball is also available (for Windows users).
```

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

### Track redirection with Response.history

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

Inspect the Response.history list to view previous Response objects created during location redirection, ordered from oldest to most recent.

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

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

>>> r.status_code
200

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

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

### Inspect and override response encoding with r.encoding

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

Inspect the encoding guessed by Requests and change it by assigning a new value to r.encoding. Requests will use the updated encoding for subsequent r.text calls.

```python
>>> r.encoding
'utf-8'
>>> r.encoding = 'ISO-8859-1'
```

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

### Pass custom HTTP headers using headers parameter

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

Pass a dictionary to the headers parameter to set custom request headers. Custom headers have lower precedence than specific sources like netrc or auth parameters, and header values should be strings or bytestrings.

```pycon
>>> url = 'https://api.github.com/some/endpoint'
>>> headers = {'user-agent': 'my-app/0.0.1'}

>>> r = requests.get(url, headers=headers)
```

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

### Set combined connect and read timeout

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

Applies a single timeout value to both the connect and read timeouts. By default, requests do not time out unless explicitly set.

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

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

### Define and use custom authentication with AuthBase

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

Subclass AuthBase and implement __call__ to modify request headers before dispatch. Pass an instance of the custom authentication class to the auth parameter of request methods.

```python
from requests.auth import AuthBase

class PizzaAuth(AuthBase):
    """Attaches HTTP Pizza Authentication to the given Request object."""
    def __init__(self, username):
        # setup any auth-related data here
        self.username = username

    def __call__(self, r):
        # modify and return the request
        r.headers['X-Pizza'] = self.username
        return r
```

```python
>>> requests.get('http://pizzabin.org/admin', auth=PizzaAuth('kenneth'))
<Response [200]>
```

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

### Ensure streamed connections are closed using with statement

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

Wraps a streamed request in a context manager to guarantee connection release back to the pool. Use when partially reading or not reading response bodies.

```python
with requests.get('https://httpbin.org/get', stream=True) as r:
    # Do things with the response here.
```

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

### Configuring Automatic Retries with urllib3 Retry

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

Configures automatic request retries with backoff and HTTP status code triggers using urllib3.util.Retry mounted through an HTTPAdapter. By default, Requests does not retry failed connections.

```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))
```

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

### Iterate over streaming responses with iter_lines

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

Set stream=True in request calls to iterate line-by-line over streaming APIs. Filter out empty lines to ignore keep-alive signals.

```python
import json
import requests

r = requests.get('https://httpbin.org/stream/20', stream=True)

for line in r.iter_lines():

    # filter out keep-alive new lines
    if line:
        decoded_line = line.decode('utf-8')
        print(json.loads(decoded_line))
```

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

### Set Persistent Client Side Certificate on Session

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

Persist a client-side certificate across requests by assigning the certificate file path to the Session cert attribute.

```python
s = requests.Session()
s.cert = '/path/client.cert'
```

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

### Compare status code with requests.codes lookup object

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

Use the built-in requests.codes lookup object to reference and compare HTTP status codes by name.

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

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

### Inspect headers without downloading body using requests.head

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

Sends an HTTP HEAD request to retrieve response headers without downloading the full page body. Useful for checking API rate limit headers.

```python
>>> r = requests.head(url=url, auth=auth)
>>> print(r.headers)
...
'x-ratelimit-remaining': '4995'
'x-ratelimit-limit': '5000'
...
```

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

### Verify successful response with Response.raise_for_status()

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

Call raise_for_status() on a response with a 200 status code, which returns None without raising an exception.

```python
>>> r.raise_for_status()
None
```

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

### Conditionally retrieve content from response headers

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

Inspects response headers prior to reading the full response body when stream=True is active. Prevents downloading content that exceeds size limits.

```python
if int(r.headers['content-length']) < TOO_LONG:
  content = r.content
  ...
```

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

### Making Digest Authentication requests using HTTPDigestAuth

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

Authenticate HTTP requests using Digest Authentication with Requests' built-in HTTPDigestAuth handler.

```python
>>> from requests.auth import HTTPDigestAuth
>>> url = 'https://httpbin.org/digest-auth/auth/user/pass'
>>> requests.get(url, auth=HTTPDigestAuth('user', 'pass'))
<Response [200]>
```

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

### Send cookies using RequestsCookieJar

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

Pass a RequestsCookieJar to manage cookies with more complete path and domain-specific rules.

```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
'{"cookies": {"tasty_cookie": "yum"}}'
```

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

### HTML multiple file upload input element

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

HTML input field definition configured with multiple="true" to accept multiple file selections under a single field name.

```html
<input type="file" name="images" multiple="true" required="true"/>
```

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

### Access binary response body with r.content

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

Access the response body as raw bytes for non-text requests. Transfer-encodings like gzip, deflate, and br (with brotli/brotlicffi) are automatically decoded.

```python
>>> r.content
b'[{"repository":{"open_issues":0,"url":"https://github.com/...
```

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

### Post automatic JSON payload with json parameter

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

Pass a dictionary directly to the json parameter to automatically encode it and set the Content-Type header to application/json. The json parameter is ignored if data or files is passed.

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

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

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

### Disable SSL Verification with verify=False

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

Disables SSL certificate verification for development or testing. Note that this accepts any TLS certificate and exposes the connection to man-in-the-middle attacks.

```python
>>> requests.get('https://kennethreitz.org', verify=False)
<Response [200]>
```

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

### Send multiple values per key using tuples or lists in data

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

Pass a list of tuples or a dictionary with list values to the data parameter when an HTML form has multiple elements sharing the same key.

```pycon
>>> 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)
{
  ...
  "form": {
    "key1": [
      "value1",
      "value2"
    ]
  },
  ...
}
>>> # httpbin may embed non-deterministic metadata,
>>> # so we only compare our submitted data here.
>>> r1.json()['form'] == r2.json()['form']
True
```

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

### Disable netrc authentication via Session trust_env

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

Set trust_env to False on a requests Session to prevent Requests from reading authentication credentials from ~/.netrc.

```python
>>> s = requests.Session()
>>> s.trust_env = False
>>> s.get('https://httpbin.org/basic-auth/user/pass')
```

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

### Send form-encoded data with data parameter dictionary

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

Pass a dictionary to the data parameter to automatically form-encode data for a POST request.

```pycon
>>> payload = {'key1': 'value1', 'key2': 'value2'}

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

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

### Override CA bundle path with REQUESTS_CA_BUNDLE

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

Set the REQUESTS_CA_BUNDLE environment variable to specify a custom certificate bundle path when routing HTTPS requests through a proxy.

```bash
$ export REQUESTS_CA_BUNDLE="/usr/local/myproxy_info/cacert.pem"
$ export https_proxy="http://10.10.1.10:1080"

$ python
>>> import requests
>>> requests.get('https://example.org')
```

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

### Delete a resource using requests.delete

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

Sends an HTTP DELETE request to remove a resource such as a GitHub comment. Returns a 204 No Content status code upon success.

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

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

### Check response status_code

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

Inspect the integer HTTP status code returned by the server on a Response object.

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

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

### Disable timeout with None

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

Tells Requests to wait indefinitely for a response by setting timeout to None.

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

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

### Raise HTTPError on bad status with Response.raise_for_status()

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

Raise an HTTPError exception for 4XX client error or 5XX server error responses.

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

>>> bad_r.raise_for_status()
Traceback (most recent call last):
  File "requests/models.py", line 832, in raise_for_status
    raise http_error
requests.exceptions.HTTPError: 404 Client Error
```

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

### Post JSON string explicitly with json.dumps()

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

Pass a JSON-encoded string to data to post non-form data directly. This approach will not set the Content-Type header to application/json.

```pycon
>>> import json

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

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

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

### Stream lines with decode_unicode and fallback encoding

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

When passing decode_unicode=True to iter_lines(), set a fallback response encoding if the server does not specify one.

```python
r = requests.get('https://httpbin.org/stream/20', stream=True)

if r.encoding is None:
    r.encoding = 'utf-8'

for line in r.iter_lines(decode_unicode=True):
    if line:
        print(json.loads(line))
```

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

### Client Certificate SSLError on Invalid Path or Key

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

An SSLError is raised when an invalid certificate or incorrect path is provided. Note that private keys for local certificates must be unencrypted.

```python
>>> requests.get('https://kennethreitz.org', cert='/wrong_path/client.pem')
SSLError: [Errno 336265225] _ssl.c:347: error:140B0009:SSL routines:SSL_CTX_use_PrivateKey_file:PEM lib
```

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

### Pass method-level cookies without session persistence

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

Shows that cookies passed directly to a request method are not persisted across subsequent requests on the session.

```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": {}}'
```

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

### Parse JSON responses using Response.json()

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

Call Response.json() as a method on response objects in Requests 1.x. The call raises an exception if JSON decoding fails.

```python
import requests
r = requests.get('https://api.github.com/events')
r.json()   # This *call* raises an exception if JSON decoding fails
```

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

### Send chunk-encoded requests using a generator

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

Pass a generator or iterator without a length to data to transmit a chunk-encoded request payload. Incoming chunk-encoded responses can be read chunk-by-chunk using Response.iter_content().

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

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

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

### Access response cookies

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

Access cookies received in a response using the r.cookies dictionary-like interface.

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

>>> r.cookies['example_cookie_name']
'example_cookie_value'
```

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

### Implement automatic sleep-retries with make_throttle_hook

Source: https://github.com/psf/requests/wiki/Cookbook

Defines a response hook generator that sleeps and retries requests with exponentially increasing timeout when receiving a 403 status code containing 'too_many' in the response body. Stops retrying and returns the response once the timeout reaches or exceeds 1025 seconds.

```python
def make_throttle_hook(timeout=2):
    """Returns a response hook function which sleeps for <timeout> seconds if
       the response status_code/content meet certain criteria before
       re-requesting the content. The timeout length grows for each re-request
       until it exceeds a threshold, at which point simply return the response object.
    """

    import time 
    def myhook(resp):
        if timeout < 1025:
            if (resp.status_code == 403) and ("too_many" in resp.content):
                time.sleep(timeout)
                proxies = resp.request.proxies
                cookies = resp.request.cookies
                auth = resp.request.auth
                hooks = {'response': make_throttle_hook(timeout=timeout*3)}
                return requests.get(resp.url, proxies=proxies, cookies=cookies, auth=auth, hooks=hooks)
        return resp
    return myhook

resp = requests.get(url, hooks={'response': make_throttle_hook(5)})
```

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

### Access raw socket response content with r.raw

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

Set stream=True on the request to access the raw socket response using r.raw. Unlike iter_content, r.raw returns untransformed raw bytes without automatically decoding gzip or deflate transfer-encodings.

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

>>> r.raw
<urllib3.response.HTTPResponse object at 0x101194810>

>>> r.raw.read(10)
b'\x1f\x8b\x08\x00\x00\x00\x00\x00\x00\x03'
```

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

### Decode JSON response content using r.json()

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

Parse JSON response data into Python objects using r.json(). If decoding fails (such as on 204 No Content or invalid JSON), requests.exceptions.JSONDecodeError is raised. Note that successful JSON decoding does not indicate HTTP request success.

```python
>>> import requests

>>> r = requests.get('https://api.github.com/events')
>>> r.json()
[{'repository': {'open_issues': 0, 'url': 'https://github.com/...
```

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

### Read decoded response text with r.text

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

Access decoded server response text using the r.text property. Requests automatically decodes content based on HTTP headers.

```python
>>> import requests

>>> r = requests.get('https://api.github.com/events')
>>> r.text
'[{"repository":{"open_issues":0,"url":"https://github.com/...
```

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

### Access parsed Link headers using response links attribute

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

Accesses parsed Link header relations directly via the r.links dictionary. Requests automatically parses links into URL and rel pairs.

```python
>>> r.links["next"]
{'url': 'https://api.github.com/users/kennethreitz/repos?page=2&per_page=10', 'rel': 'next'}

>>> r.links["last"]
{'url': 'https://api.github.com/users/kennethreitz/repos?page=7&per_page=10', 'rel': 'last'}
```

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

### Raising InvalidURL on Invalid URL Escape Sequence

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

Demonstrates URL validation behavior in Requests 2.x. An invalid URL escape sequence now raises a subclass of RequestException (requests.exceptions.InvalidURL) instead of a ValueError.

```python
requests.get('http://%zz/')   # raises requests.exceptions.InvalidURL
```

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

### Iterate safely over non-reentrant iter_lines iterator

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

iter_lines is not reentrant safe. Save the iterator object directly when consuming items across multiple locations to avoid data loss.

```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)
```
Tokens:
Raw