| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263 |
- .. _api:
- 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
- Request Sessions
- ----------------
- .. _sessionapi:
- .. 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.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
- .. _api-cookies:
- Cookies
- -------
- .. autofunction:: requests.utils.dict_from_cookiejar
- .. autofunction:: requests.utils.cookiejar_from_dict
- .. autofunction:: requests.utils.add_dict_to_cookiejar
- .. autoclass:: requests.cookies.RequestsCookieJar
- :inherited-members:
- .. autoclass:: requests.cookies.CookieConflictError
- :inherited-members:
- Status Code Lookup
- ------------------
- .. autoclass:: requests.codes
- ::
- >>> requests.codes['temporary_redirect']
- 307
- >>> requests.codes.teapot
- 418
- >>> requests.codes['\o/']
- 200
- 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_.
- .. _requests-oauthlib: https://github.com/requests/requests-oauthlib
- .. _requests-kerberos: https://github.com/requests/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)
- 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("requests.packages.urllib3")
- requests_log.setLevel(logging.DEBUG)
- requests_log.propagate = True
- requests.get('http://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.
- .. _ISC: http://opensource.org/licenses/ISC
- .. _Apache 2.0: http://opensource.org/licenses/Apache-2.0
- 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.
- .. _blog: http://lukasa.co.uk/2013/09/Requests_20/
- 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 Python2 or bytestrings on Python 3)
- they will be converted to the native string type assuming UTF-8 encoding.
|