api.rst 4.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195
  1. .. _api:
  2. Developer Interface
  3. ===================
  4. .. module:: requests
  5. This part of the documentation covers all the interfaces of Requests. For
  6. parts where Requests depends on external libraries, we document the most
  7. important right here and provide links to the canonical documentation.
  8. Main Interface
  9. --------------
  10. All of Requests' functionality can be accessed by these 7 methods.
  11. They all return an instance of the :class:`Response <Response>` object.
  12. .. autofunction:: request
  13. .. autofunction:: head
  14. .. autofunction:: get
  15. .. autofunction:: post
  16. .. autofunction:: put
  17. .. autofunction:: patch
  18. .. autofunction:: delete
  19. Lower-Level Classes
  20. ~~~~~~~~~~~~~~~~~~~
  21. .. autoclass:: requests.Request
  22. :inherited-members:
  23. .. autoclass:: Response
  24. :inherited-members:
  25. Request Sessions
  26. ----------------
  27. .. autoclass:: Session
  28. :inherited-members:
  29. .. autoclass:: requests.adapters.HTTPAdapter
  30. :inherited-members:
  31. Exceptions
  32. ~~~~~~~~~~
  33. .. autoexception:: requests.exceptions.RequestException
  34. .. autoexception:: requests.exceptions.ConnectionError
  35. .. autoexception:: requests.exceptions.HTTPError
  36. .. autoexception:: requests.exceptions.URLRequired
  37. .. autoexception:: requests.exceptions.TooManyRedirects
  38. Status Code Lookup
  39. ~~~~~~~~~~~~~~~~~~
  40. .. autofunction:: requests.codes
  41. ::
  42. >>> requests.codes['temporary_redirect']
  43. 307
  44. >>> requests.codes.teapot
  45. 418
  46. >>> requests.codes['\o/']
  47. 200
  48. Cookies
  49. ~~~~~~~
  50. .. autofunction:: requests.utils.dict_from_cookiejar
  51. .. autofunction:: requests.utils.cookiejar_from_dict
  52. .. autofunction:: requests.utils.add_dict_to_cookiejar
  53. Encodings
  54. ~~~~~~~~~
  55. .. autofunction:: requests.utils.get_encodings_from_content
  56. .. autofunction:: requests.utils.get_encoding_from_headers
  57. .. autofunction:: requests.utils.get_unicode_from_response
  58. Classes
  59. ~~~~~~~
  60. .. autoclass:: requests.Response
  61. :inherited-members:
  62. .. autoclass:: requests.Request
  63. :inherited-members:
  64. .. autoclass:: requests.PreparedRequest
  65. :inherited-members:
  66. .. _sessionapi:
  67. .. autoclass:: requests.Session
  68. :inherited-members:
  69. .. autoclass:: requests.adapters.HTTPAdapter
  70. :inherited-members:
  71. Migrating to 1.x
  72. ----------------
  73. This section details the main differences between 0.x and 1.x and is meant
  74. to ease the pain of upgrading.
  75. API Changes
  76. ~~~~~~~~~~~
  77. * ``Response.json`` is now a callable and not a property of a response.
  78. ::
  79. import requests
  80. r = requests.get('https://github.com/timeline.json')
  81. r.json() # This *call* raises an exception if JSON decoding fails
  82. * The ``Session`` API has changed. Sessions objects no longer take parameters.
  83. ``Session`` is also now capitalized, but it can still be
  84. instantiated with a lowercase ``session`` for backwards compatibility.
  85. ::
  86. s = requests.Session() # formerly, session took parameters
  87. s.auth = auth
  88. s.headers.update(headers)
  89. r = s.get('http://httpbin.org/headers')
  90. * All request hooks have been removed except 'response'.
  91. * Authentication helpers have been broken out into separate modules. See
  92. requests-oauthlib_ and requests-kerberos_.
  93. .. _requests-oauthlib: https://github.com/requests/requests-oauthlib
  94. .. _requests-kerberos: https://github.com/requests/requests-kerberos
  95. * The parameter for streaming requests was changed from ``prefetch`` to
  96. ``stream`` and the logic was inverted. In addition, ``stream`` is now
  97. required for raw response reading.
  98. ::
  99. # in 0.x, passing prefetch=False would accomplish the same thing
  100. r = requests.get('https://github.com/timeline.json', stream=True)
  101. for chunk in r.iter_content(8192):
  102. ...
  103. * The ``config`` parameter to the requests method has been removed. Some of
  104. these options are now configured on a ``Session`` such as keep-alive and
  105. maximum number of redirects. The verbosity option should be handled by
  106. configuring logging.
  107. ::
  108. import requests
  109. import logging
  110. # these two lines enable debugging at httplib level (requests->urllib3->httplib)
  111. # you will see the REQUEST, including HEADERS and DATA, and RESPONSE with HEADERS but without DATA.
  112. # the only thing missing will be the response.body which is not logged.
  113. import httplib
  114. httplib.HTTPConnection.debuglevel = 1
  115. logging.basicConfig() # you need to initialize logging, otherwise you will not see anything from requests
  116. logging.getLogger().setLevel(logging.DEBUG)
  117. requests_log = logging.getLogger("requests.packages.urllib3")
  118. requests_log.setLevel(logging.DEBUG)
  119. requests_log.propagate = True
  120. requests.get('http://httpbin.org/headers')
  121. Licensing
  122. ~~~~~~~~~
  123. One key difference that has nothing to do with the API is a change in the
  124. license from the ISC_ license to the `Apache 2.0`_ license. The Apache 2.0
  125. license ensures that contributions to Requests are also covered by the Apache
  126. 2.0 license.
  127. .. _ISC: http://opensource.org/licenses/ISC
  128. .. _Apache 2.0: http://opensource.org/licenses/Apache-2.0