Skip to content

Latest commit

 

History

History
177 lines (115 loc) · 4.03 KB

api.rst

File metadata and controls

177 lines (115 loc) · 4.03 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 Request's 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

Lower-Level Classes

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


.. autoclass:: Response
   :inherited-members:

Request Sessions

.. autoclass:: Session
   :inherited-members:

Exceptions

.. module:: requests


.. autoexception:: RequestException

.. autoexception:: ConnectionError

.. autoexception:: HTTPError

.. autoexception:: URLRequired

.. autoexception:: TooManyRedirects

Status Code Lookup

.. autofunction:: requests.codes


>>> requests.codes['temporary_redirect']
307

>>> requests.codes.teapot
418

>>> requests.codes['\o/']
200

Cookies

.. autofunction:: dict_from_cookiejar

.. autofunction:: cookiejar_from_dict

.. autofunction:: add_dict_to_cookiejar

Encodings

.. autofunction:: get_encodings_from_content

.. autofunction:: get_encoding_from_headers

.. autofunction:: get_unicode_from_response

.. autofunction:: decode_gzip

Classes

.. autoclass:: requests.Response
   :inherited-members:


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


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


.. autoclass:: requests.Session
   :inherited-members:

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://github.com/timeline.json')
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('http://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://github.com/timeline.json', stream=True)
r.raw.read(10)

  • 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.

    # Verbosity should now be configured with logging
my_config = {'verbose': sys.stderr}
requests.get('http://httpbin.org/headers', config=my_config)  # bad!

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.