api.py 4.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131
  1. # -*- coding: utf-8 -*-
  2. """
  3. requests.api
  4. ~~~~~~~~~~~~
  5. This module implements the Requests API.
  6. :copyright: (c) 2012 by Kenneth Reitz.
  7. :license: Apache2, see LICENSE for more details.
  8. """
  9. from . import sessions
  10. def request(method, url, **kwargs):
  11. """Constructs and sends a :class:`Request <Request>`.
  12. Returns :class:`Response <Response>` object.
  13. :param method: method for the new :class:`Request` object.
  14. :param url: URL for the new :class:`Request` object.
  15. :param params: (optional) Dictionary or bytes to be sent in the query string for the :class:`Request`.
  16. :param data: (optional) Dictionary, bytes, or file-like object to send in the body of the :class:`Request`.
  17. :param json: (optional) json data to send in the body of the :class:`Request`.
  18. :param headers: (optional) Dictionary of HTTP Headers to send with the :class:`Request`.
  19. :param cookies: (optional) Dict or CookieJar object to send with the :class:`Request`.
  20. :param files: (optional) Dictionary of ``'name': file-like-objects`` (or ``{'name': ('filename', fileobj)}``) for multipart encoding upload.
  21. :param auth: (optional) Auth tuple to enable Basic/Digest/Custom HTTP Auth.
  22. :param timeout: (optional) How long to wait for the server to send data
  23. before giving up, as a float, or a (`connect timeout, read timeout
  24. <user/advanced.html#timeouts>`_) tuple.
  25. :type timeout: float or tuple
  26. :param allow_redirects: (optional) Boolean. Set to True if POST/PUT/DELETE redirect following is allowed.
  27. :type allow_redirects: bool
  28. :param proxies: (optional) Dictionary mapping protocol to the URL of the proxy.
  29. :param verify: (optional) if ``True``, the SSL cert will be verified. A CA_BUNDLE path can also be provided.
  30. :param stream: (optional) if ``False``, the response content will be immediately downloaded.
  31. :param cert: (optional) if String, path to ssl client cert file (.pem). If Tuple, ('cert', 'key') pair.
  32. Usage::
  33. >>> import requests
  34. >>> req = requests.request('GET', 'http://httpbin.org/get')
  35. <Response [200]>
  36. """
  37. session = sessions.Session()
  38. response = session.request(method=method, url=url, **kwargs)
  39. # By explicitly closing the session, we avoid leaving sockets open which
  40. # can trigger a ResourceWarning in some cases, and look like a memory leak
  41. # in others.
  42. session.close()
  43. return response
  44. def get(url, **kwargs):
  45. """Sends a GET request. Returns :class:`Response` object.
  46. :param url: URL for the new :class:`Request` object.
  47. :param \*\*kwargs: Optional arguments that ``request`` takes.
  48. """
  49. kwargs.setdefault('allow_redirects', True)
  50. return request('get', url, **kwargs)
  51. def options(url, **kwargs):
  52. """Sends a OPTIONS request. Returns :class:`Response` object.
  53. :param url: URL for the new :class:`Request` object.
  54. :param \*\*kwargs: Optional arguments that ``request`` takes.
  55. """
  56. kwargs.setdefault('allow_redirects', True)
  57. return request('options', url, **kwargs)
  58. def head(url, **kwargs):
  59. """Sends a HEAD request. Returns :class:`Response` object.
  60. :param url: URL for the new :class:`Request` object.
  61. :param \*\*kwargs: Optional arguments that ``request`` takes.
  62. """
  63. kwargs.setdefault('allow_redirects', False)
  64. return request('head', url, **kwargs)
  65. def post(url, data=None, json=None, **kwargs):
  66. """Sends a POST request. Returns :class:`Response` object.
  67. :param url: URL for the new :class:`Request` object.
  68. :param data: (optional) Dictionary, bytes, or file-like object to send in the body of the :class:`Request`.
  69. :param json: (optional) json data to send in the body of the :class:`Request`.
  70. :param \*\*kwargs: Optional arguments that ``request`` takes.
  71. """
  72. return request('post', url, data=data, json=json, **kwargs)
  73. def put(url, data=None, **kwargs):
  74. """Sends a PUT request. Returns :class:`Response` object.
  75. :param url: URL for the new :class:`Request` object.
  76. :param data: (optional) Dictionary, bytes, or file-like object to send in the body of the :class:`Request`.
  77. :param \*\*kwargs: Optional arguments that ``request`` takes.
  78. """
  79. return request('put', url, data=data, **kwargs)
  80. def patch(url, data=None, **kwargs):
  81. """Sends a PATCH request. Returns :class:`Response` object.
  82. :param url: URL for the new :class:`Request` object.
  83. :param data: (optional) Dictionary, bytes, or file-like object to send in the body of the :class:`Request`.
  84. :param \*\*kwargs: Optional arguments that ``request`` takes.
  85. """
  86. return request('patch', url, data=data, **kwargs)
  87. def delete(url, **kwargs):
  88. """Sends a DELETE request. Returns :class:`Response` object.
  89. :param url: URL for the new :class:`Request` object.
  90. :param \*\*kwargs: Optional arguments that ``request`` takes.
  91. """
  92. return request('delete', url, **kwargs)