Requests

https://requests.readthedocs.io/en/latest
Admin
Requests is a Python HTTP library that simplifies making HTTP requests with an elegant and...
Tokens:160,907
Snippets:1,055
Trust Score:8.3
Update:18 hours ago
Show doc for...
Tokens:
Raw
### Basic Requests usage example

Source: https://requests.readthedocs.io/en/latest/

Shows how to make a GET request with authentication, then access the response status code, headers, encoding, text, and JSON data. The example uses the GitHub API and demonstrates the library's simple interface.

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

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

### Install Requests from source

Source: https://requests.readthedocs.io/en/latest/user/install/

After obtaining a copy of the source, change to the requests directory and install it into site-packages using pip.

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

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

### Install Requests with pip

Source: https://requests.readthedocs.io/en/latest/user/install/

Run this command in your terminal to install the Requests library using pip.

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

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

### Install SOCKS dependencies

Source: https://requests.readthedocs.io/en/latest/user/advanced/

Install the optional dependencies for SOCKS proxy support using pip.

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

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

### PreparedRequest class docstring usage example

Source: https://requests.readthedocs.io/en/latest/_modules/requests/models/

Shows the intended usage of PreparedRequest: create a Request, prepare it, and send it via a Session. The example demonstrates the expected output of the prepared request and the response.

```python
      >>> import requests
      >>> req = requests.Request('GET', 'https://httpbin.org/get')
      >>> r = req.prepare()
      >>> r
      <PreparedRequest [GET]>

      >>> s = requests.Session()
      >>> s.send(r)
      <Response [200]>
```

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

### HTTPAdapter usage example

Source: https://requests.readthedocs.io/en/latest/_modules/requests/adapters/

Shows how to create an HTTPAdapter with max_retries=3 and mount it on a session for the 'http://' scheme.

```python
>>> import requests
>>> s = requests.Session()
>>> a = requests.adapters.HTTPAdapter(max_retries=3)
>>> s.mount('http://', a)
```

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

### Basic Session usage

Source: https://requests.readthedocs.io/en/latest/_modules/requests/sessions/

Shows how to create a Session and make a GET request, returning a Response object.

```python
>>> import requests
>>> s = requests.Session()
>>> s.get('https://httpbin.org/get')
<Response [200]>
```

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

### Install Requests with security extras

Source: https://requests.readthedocs.io/en/latest/community/updates/

Install the 'security' package extras set for Requests, which includes Certifi and other security-related dependencies.

```bash
pip install requests[security]
```

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

### Create and prepare a requests.Request

Source: https://requests.readthedocs.io/en/latest/api/

Shows how to instantiate a requests.Request with a GET method and URL, then call prepare() to construct a PreparedRequest. The output is a PreparedRequest object.

```python
>>> import requests
>>> req = requests.Request('GET', 'https://httpbin.org/get')
>>> req.prepare()
<PreparedRequest [GET]>
```

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

### OPTIONS request to check supported methods

Source: https://requests.readthedocs.io/en/latest/user/advanced/

Sends an OPTIONS request to a URL to see which HTTP methods are supported. The example shows a 500 status from GitHub, indicating OPTIONS is not implemented, and a hypothetical example showing the 'allow' header.

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

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

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

### requests.request() usage example

Source: https://requests.readthedocs.io/en/latest/api/

Shows how to use requests.request() to send a GET request to httpbin.org and receive a Response object with status 200.

```python
>>> import requests
>>> req = requests.request('GET', 'https://httpbin.org/get')
>>> req
<Response [200]>
```

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

### Prepare and send a request with requests.PreparedRequest

Source: https://requests.readthedocs.io/en/latest/api/

Shows how to create a PreparedRequest from a Request object and send it using a Session. The example uses httpbin.org/get and expects a 200 response.

```python
>>> import requests
>>> req = requests.Request('GET', 'https://httpbin.org/get')
>>> r = req.prepare()
>>> r
<PreparedRequest [GET]>

>>> s = requests.Session()
>>> s.send(r)
<Response [200]>
```

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

### Install requests with chardet extra

Source: https://requests.readthedocs.io/en/latest/community/updates/

Use this shell command to install Requests with the chardet dependency on Python 3, overriding the default charset_normalizer. This is useful for backwards compatibility when chardet is already installed.

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

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

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

Source: https://requests.readthedocs.io/en/latest/user/quickstart/

Examples of other HTTP request types: PUT, DELETE, HEAD, and OPTIONS.

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

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

### Successful SSL verification example

Source: https://requests.readthedocs.io/en/latest/user/advanced/

Shows a successful HTTPS request when the certificate is valid, returning a 200 response.

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

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

### Make a GET request to Wikipedia

Source: https://requests.readthedocs.io/en/latest/user/advanced/

Creates a Request object and sends it to the server, returning a Response object. This is the initial step for accessing response and request headers.

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

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

### Check response status code

Source: https://requests.readthedocs.io/en/latest/user/quickstart/

Use `r.status_code` to get the HTTP status code of a response. The example shows a successful GET request returning 200.

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

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

### Access headers case-insensitively

Source: https://requests.readthedocs.io/en/latest/user/quickstart/

HTTP header names are case-insensitive, so you can access them with any capitalization. The example shows both bracket and get() access.

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

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

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

### Digest Authentication with HTTPDigestAuth

Source: https://requests.readthedocs.io/en/latest/user/authentication/

Use HTTPDigestAuth to authenticate a request with digest authentication. The example shows a GET request to httpbin.org with username 'user' and password 'pass', returning a 200 response.

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

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

### OAuth 1 Authentication with OAuth1

Source: https://requests.readthedocs.io/en/latest/user/authentication/

Use requests-oauthlib's OAuth1 to make an OAuth 1 authenticated request. The example shows a GET request to Twitter's API with placeholder credentials, returning a 200 response.

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

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

### get method: Send a GET request

Source: https://requests.readthedocs.io/en/latest/_modules/requests/sessions/

Convenience method that sends a GET request using the request method. Accepts URL, optional params, and additional keyword arguments for the request.

```python
    def get(
        self,
        url: _t.UriType,
        params: _t.ParamsType = None,
        **kwargs: Unpack[_t.GetKwargs],
    ) -> Response:
        r"""Sends a GET request. Returns :class:`Response` object."""
```

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

### PreparedRequest.__init__ method

Source: https://requests.readthedocs.io/en/latest/_modules/requests/models/

Initializes a PreparedRequest with default values for method, URL, headers, cookies, body, hooks, and body position.

```python
    def __init__(self) -> None:
        #: HTTP verb to send to the server.
        self.method = None
        #: HTTP URL to send the request to.
        self.url = None
        #: dictionary of HTTP headers.
        self.headers = None  # type: ignore[assignment]
        # The `CookieJar` used to create the Cookie header will be stored here
        # after prepare_cookies is called
        self._cookies = None
        #: request body to send to the server.
        self.body = None
        #: dictionary of callback hooks, for internal usage.
        self.hooks = default_hooks()
        #: integer denoting starting position of a readable file-like body.
        self._body_position = None
```

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

### Import the Requests module

Source: https://requests.readthedocs.io/en/latest/user/quickstart/

Begin by importing the Requests module.

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

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

### prepare_url: Prepare HTTP URL with params

Source: https://requests.readthedocs.io/en/latest/_modules/requests/models/

Prepares the URL by decoding bytes, stripping whitespace, handling non-HTTP schemes, validating scheme/host, IDNA-encoding non-ASCII hosts, and appending encoded params. Raises MissingSchema, InvalidURL, or UnicodeError on invalid input.

```python
[docs]
    def prepare_url(
        self,
        url: _t.UriType,
        params: _t.ParamsType,
    ) -> None:
        """Prepares the given HTTP URL."""
        #: Accept objects that have string representations.
        #: We're unable to blindly call unicode/str functions
        #: as this will include the bytestring indicator (b'')
        #: on python 3.x.
        #: https://github.com/psf/requests/pull/2238
        if isinstance(url, bytes):
            url = url.decode("utf8")
        else:
            url = str(url)

        # Remove leading whitespaces from url
        url = url.lstrip()

        # Don't do any URL preparation for non-HTTP schemes like `mailto`,
        # `data` etc to work around exceptions from `url_parse`, which
        # handles RFC 3986 only.
        if ":" in url and not url.lower().startswith("http"):
            self.url = url
            return

        # Support for unicode domain names and paths.
        try:
            scheme, auth, host, port, path, query, fragment = parse_url(url)
        except LocationParseError as e:
            raise InvalidURL(*e.args)

        if not scheme:
            raise MissingSchema(
                f"Invalid URL {url!r}: No scheme supplied. "
                f"Perhaps you meant https://{url}?"
            )

        if not host:
            raise InvalidURL(f"Invalid URL {url!r}: No host supplied")

        # In general, we want to try IDNA encoding the hostname if the string contains
        # non-ASCII characters. This allows users to automatically get the correct IDNA
        # behaviour. For strings containing only ASCII characters, we need to also verify
        # it doesn't start with a wildcard (*), before allowing the unencoded hostname.
        if not unicode_is_ascii(host):
            try:
                host = self._get_idna_encoded_host(host)
            except UnicodeError:
                raise InvalidURL("URL has an invalid label.")
        elif host.startswith(("*", ".")):
            raise InvalidURL("URL has an invalid label.")

        # Carefully reconstruct the network location
        netloc = auth or ""
        if netloc:
            netloc += "@"
        netloc += host
        if port:
            netloc += f":{port}"

        # Bare domains aren't valid URLs.
        if not path:
            path = "/"

        if isinstance(params, (str, bytes)):
            params = to_native_string(params)

        if params is not None:
            enc_params = self._encode_params(params)
        else:
            enc_params = ""

        if enc_params:
            if query:
                query = f"{query}&{enc_params}"
            else:
                query = enc_params

        url = requote_uri(urlunparse((scheme, netloc, path, "", query, fragment)))
        self.url = url
```

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

### get(url, params=None, **kwargs)

Source: https://requests.readthedocs.io/en/latest/_modules/requests/api/

Sends a GET request to the specified URL. Accepts optional query parameters and any additional arguments supported by the request function.

```APIDOC
## get(url, params=None, **kwargs)

### Description
Sends a GET request to the specified URL. This is a convenience wrapper around the request function with method set to 'get'.

### Method
Function call

### Signature
`get(url: UriType, params: ParamsType = None, **kwargs) -> Response`

### Parameters
- **url** (UriType) - Required - URL for the new Request object.
- **params** (optional) - Dictionary, list of tuples, or bytes to send in the query string.
- **kwargs** - Optional arguments that request takes.

### Return Value
Returns a Response object.
```

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

### GET an issue and its comments from GitHub API

Source: https://requests.readthedocs.io/en/latest/user/advanced/

Retrieves a GitHub issue and its comments using GET requests, then parses the JSON response to access issue details and comment bodies.

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

>>> issue = json.loads(r.text)

>>> print(issue['title'])
Feature any http verb in docs

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

```python
>>> r = requests.get(r.url + '/comments')
>>> r.status_code
200

>>> comments = r.json()

>>> print(comments[0].keys())
['body', 'url', 'created_at', 'updated_at', 'user', 'id']

>>> print(comments[2]['body'])
Probably in the "advanced" section
```

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

### Session.get(url, params=None, **kwargs)

Source: https://requests.readthedocs.io/en/latest/_modules/requests/sessions/

Sends a GET request. Returns a Response object. This method is a convenience wrapper around the request method, setting the HTTP method to GET.

```APIDOC
## Session.get(url, params=None, **kwargs)

### Description
Sends a GET request. Returns :class:`Response` object.

### Method
`get`

### Signature
```python
def get(
    self,
    url: _t.UriType,
    params: _t.ParamsType = None,
    **kwargs: Unpack[_t.GetKwargs],
) -> Response:
```

### Parameters
- **url** (_t.UriType) - Required - URL for the new :class:`Request` object.
- **params** (_t.ParamsType) - Optional - Dictionary or bytes to be sent in the query string for the :class:`Request`.
- **kwargs** (Unpack[_t.GetKwargs]) - Optional - Additional keyword arguments to pass to the underlying request method.

### Returns
- **Response** - The :class:`Response <Response>` object.

### Example
```python
session = requests.Session()
response = session.get('https://httpbin.org/get')
```
```

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

### GET a commit from GitHub API

Source: https://requests.readthedocs.io/en/latest/user/advanced/

Performs a GET request to retrieve a specific commit from the GitHub API. The response status and content-type are checked to confirm success and determine the content type.

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

```python
>>> if r.status_code == requests.codes.ok:
...     print(r.headers['content-type'])
...
application/json; charset=utf-8
```

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

### Enable redirection for HEAD with allow_redirects=True

Source: https://requests.readthedocs.io/en/latest/user/quickstart/

Shows how to enable redirection for HEAD requests by setting allow_redirects=True. The example follows the redirect and shows the final URL and history.

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

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

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

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

### SessionRedirectMixin.rebuild_method - change HTTP method on redirect

Source: https://requests.readthedocs.io/en/latest/_modules/requests/sessions/

Changes the request method based on redirect status codes: 303 and 302 become GET (except HEAD), and 301 turns POST into GET.

```python
    def rebuild_method(
        self, prepared_request: PreparedRequest, response: Response
    ) -> None:
        """When being redirected we may want to change the method of the request
        based on certain specs or browser behavior.
        """
        method = prepared_request.method

        # https://tools.ietf.org/html/rfc7231#section-6.4.4
        if response.status_code == codes.see_other and method != "HEAD":
            method = "GET"

        # Do what the browsers do, despite standards...
        # First, turn 302s into GETs.
        if response.status_code == codes.found and method != "HEAD":
            method = "GET"

        # Second, if a POST is responded to with a 301, turn it into a GET.
        # This bizarre behaviour is explained in Issue 1704.
        if response.status_code == codes.moved and method == "POST":
            method = "GET"

        prepared_request.method = method
```

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

### Use HTTP Basic Auth with proxy

Source: https://requests.readthedocs.io/en/latest/user/advanced/

Use the `http://user:password@host/` syntax in proxy configuration entries to authenticate with the proxy.

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

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

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

### Session.mount method

Source: https://requests.readthedocs.io/en/latest/_modules/requests/sessions/

Registers a connection adapter to a prefix. Adapters are sorted in descending order by prefix length, moving shorter prefixes to the end.

```python
    def mount(self, prefix: str, adapter: BaseAdapter) -> None:
        """Registers a connection adapter to a prefix.

        Adapters are sorted in descending order by prefix length.
        """
        self.adapters[prefix] = adapter
        keys_to_move = [k for k in self.adapters if len(k) < len(prefix)]

        for key in keys_to_move:
            self.adapters[key] = self.adapters.pop(key)
```

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

### Session.prepare_request(request)

Source: https://requests.readthedocs.io/en/latest/_modules/requests/sessions/

Constructs a PreparedRequest for transmission, merging settings from the Request instance and the Session. Returns the PreparedRequest object.

```APIDOC
## Session.prepare_request(request)

### Description
Constructs a :class:`PreparedRequest <PreparedRequest>` for transmission and returns it. The :class:`PreparedRequest` has settings merged from the :class:`Request <Request>` instance and those of the :class:`Session`.

### Method
prepare_request

### Parameters
- **request** (Request) - Required - :class:`Request` instance to prepare with this session's settings.

### Returns
- **PreparedRequest** - The prepared request object.

```

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

### requests.codes usage example

Source: https://requests.readthedocs.io/en/latest/api/

Shows how to access HTTP status codes by name using the requests.codes object, both as dictionary items and as attributes. The example demonstrates that requests.codes['temporary_redirect'] returns 307, requests.codes.teapot returns 418, and requests.codes['\o/'] returns 200.

```python
>>> import requests
>>> requests.codes['temporary_redirect']
307
>>> requests.codes.teapot
418
>>> requests.codes['\o/']
200
```

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

### Session.mount

Source: https://requests.readthedocs.io/en/latest/api/

Registers a connection adapter to a prefix.

```APIDOC
## Session.mount

### Description
Registers a connection adapter to a prefix. Adapters are sorted in descending order by prefix length.

### Method
Function

### Signature
`mount(prefix: str, adapter: BaseAdapter) -> None`

### Parameters
- **prefix** (str) - Required - The URL prefix to mount the adapter for.
- **adapter** (BaseAdapter) - Required - The adapter to register.

### Returns
- **None**
```

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

### Make a GET request

Source: https://requests.readthedocs.io/en/latest/user/quickstart/

Fetch GitHub's public timeline using requests.get().

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

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

### Passing a custom CA bundle to verify

Source: https://requests.readthedocs.io/en/latest/user/advanced/

Shows how to pass the path to a CA_BUNDLE file or directory with trusted CAs using the verify parameter.

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

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

### Clone Requests repository from GitHub

Source: https://requests.readthedocs.io/en/latest/user/install/

Clone the public Requests repository from GitHub to get the source code.

```bash
$ git clone https://github.com/psf/requests.git
```
Tokens:
Raw