Skip to content

Latest commit

 

History

History
260 lines (172 loc) · 7.12 KB

api.rst

File metadata and controls

260 lines (172 loc) · 7.12 KB
Raw

Developer Interface

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 Response <Response> object.

request

head

get

post

put

patch

delete

Exceptions

requests.RequestException

requests.ConnectionError

requests.HTTPError

requests.URLRequired

requests.TooManyRedirects

requests.ConnectTimeout

requests.ReadTimeout

requests.Timeout

Request Sessions

Session

Lower-Level Classes

requests.Request

Response

Lower-Lower-Level Classes

requests.PreparedRequest

requests.adapters.BaseAdapter

requests.adapters.HTTPAdapter

Authentication

requests.auth.AuthBase

requests.auth.HTTPBasicAuth

requests.auth.HTTPProxyAuth

requests.auth.HTTPDigestAuth

Encodings

requests.utils.get_encodings_from_content

requests.utils.get_encoding_from_headers

requests.utils.get_unicode_from_response

Cookies

requests.utils.dict_from_cookiejar

requests.utils.add_dict_to_cookiejar

requests.cookies.cookiejar_from_dict

requests.cookies.RequestsCookieJar

requests.cookies.CookieConflictError

Status Code Lookup

requests.codes

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://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('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://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("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.