Skip to content

Latest commit

 

History

History
261 lines (173 loc) · 7.16 KB

api.rst

File metadata and controls

261 lines (173 loc) · 7.16 KB
Raw

Developer Interface

.. module:: requests

This part of the documentation covers all the interfaces of Requests. For parts where Requests depends on external libraries, we document the most important right here and provide links to the canonical documentation.

Main Interface

All of Requests' functionality can be accessed by these 7 methods. They all return an instance of the :class:`Response <Response>` object.

.. autofunction:: request


.. autofunction:: head

.. autofunction:: get

.. autofunction:: post

.. autofunction:: put

.. autofunction:: patch

.. autofunction:: delete

Exceptions

.. autoexception:: requests.RequestException

.. autoexception:: requests.ConnectionError

.. autoexception:: requests.HTTPError

.. autoexception:: requests.URLRequired

.. autoexception:: requests.TooManyRedirects

.. autoexception:: requests.ConnectTimeout

.. autoexception:: requests.ReadTimeout

.. autoexception:: requests.Timeout

.. autoexception:: requests.JSONDecodeError

Request Sessions

.. autoclass:: Session
   :inherited-members:

Lower-Level Classes

.. autoclass:: requests.Request
   :inherited-members:


.. autoclass:: Response
   :inherited-members:

Lower-Lower-Level Classes

.. autoclass:: requests.PreparedRequest
   :inherited-members:


.. autoclass:: requests.adapters.BaseAdapter
   :inherited-members:


.. autoclass:: requests.adapters.HTTPAdapter
   :inherited-members:

Authentication

.. autoclass:: requests.auth.AuthBase

.. autoclass:: requests.auth.HTTPBasicAuth

.. autoclass:: requests.auth.HTTPProxyAuth

.. autoclass:: requests.auth.HTTPDigestAuth

Encodings

.. autofunction:: requests.utils.get_encodings_from_content

.. autofunction:: requests.utils.get_encoding_from_headers

.. autofunction:: requests.utils.get_unicode_from_response

Cookies

.. autofunction:: requests.utils.dict_from_cookiejar

.. autofunction:: requests.utils.add_dict_to_cookiejar

.. autofunction:: requests.cookies.cookiejar_from_dict


.. autoclass:: requests.cookies.RequestsCookieJar
   :inherited-members:


.. autoclass:: requests.cookies.CookieConflictError
   :inherited-members:

Status Code Lookup

.. autoclass:: requests.codes


.. automodule:: requests.status_codes

Migrating to 1.x

This section details the main differences between 0.x and 1.x and is meant to ease the pain of upgrading.

API Changes

  • Response.json is now a callable and not a property of a response.

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

  • The Session API has changed. Sessions objects no longer take parameters. Session is also now capitalized, but it can still be instantiated with a lowercase session for backwards compatibility.

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

  • All request hooks have been removed except 'response'.

  • Authentication helpers have been broken out into separate modules. See requests-oauthlib and requests-kerberos.

  • The parameter for streaming requests was changed from prefetch to stream and the logic was inverted. In addition, stream is now required for raw response reading.

    # 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):
    ...

  • The config parameter to the requests method has been removed. Some of these options are now configured on a Session such as keep-alive and maximum number of redirects. The verbosity option should be handled by configuring logging.

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

Licensing

One key difference that has nothing to do with the API is a change in the license from the ISC license to the Apache 2.0 license. The Apache 2.0 license ensures that contributions to Requests are also covered by the Apache 2.0 license.

Migrating to 2.x

Compared with the 1.0 release, there were relatively few backwards incompatible changes, but there are still a few issues to be aware of with this major release.

For more details on the changes in this release including new APIs, links to the relevant GitHub issues and some of the bug fixes, read Cory's blog on the subject.

API Changes

  • There were a couple changes to how Requests handles exceptions. RequestException is now a subclass of IOError rather than RuntimeError as that more accurately categorizes the type of error. In addition, an invalid URL escape sequence now raises a subclass of RequestException rather than a ValueError.

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

    Lastly, httplib.IncompleteRead exceptions caused by incorrect chunked encoding will now raise a Requests ChunkedEncodingError instead.

  • The proxy API has changed slightly. The scheme for a proxy URL is now required.

    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)

Behavioural Changes

  • Keys in the headers dictionary are now native strings on all Python versions, i.e. bytestrings on Python 2 and unicode on Python 3. If the keys are not native strings (unicode on Python 2 or bytestrings on Python 3) they will be converted to the native string type assuming UTF-8 encoding.
  • Values in the headers dictionary should always be strings. This has been the project's position since before 1.0 but a recent change (since version 2.11.0) enforces this more strictly. It's advised to avoid passing header values as unicode when possible.