api.py 4.2 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120
  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 headers: (optional) Dictionary of HTTP Headers to send with the :class:`Request`.
  18. :param cookies: (optional) Dict or CookieJar object to send with the :class:`Request`.
  19. :param files: (optional) Dictionary of 'name': file-like-objects (or {'name': ('filename', fileobj)}) for multipart encoding upload.
  20. :param auth: (optional) Auth tuple to enable Basic/Digest/Custom HTTP Auth.
  21. :param timeout: (optional) Float describing the timeout of the request.
  22. :param allow_redirects: (optional) Boolean. Set to True if POST/PUT/DELETE redirect following is allowed.
  23. :param proxies: (optional) Dictionary mapping protocol to the URL of the proxy.
  24. :param verify: (optional) if ``True``, the SSL cert will be verified. A CA_BUNDLE path can also be provided.
  25. :param stream: (optional) if ``False``, the response content will be immediately downloaded.
  26. :param cert: (optional) if String, path to ssl client cert file (.pem). If Tuple, ('cert', 'key') pair.
  27. Usage::
  28. >>> import requests
  29. >>> req = requests.request('GET', 'http://httpbin.org/get')
  30. <Response [200]>
  31. """
  32. session = sessions.Session()
  33. return session.request(method=method, url=url, **kwargs)
  34. def get(url, **kwargs):
  35. """Sends a GET request. Returns :class:`Response` object.
  36. :param url: URL for the new :class:`Request` object.
  37. :param \*\*kwargs: Optional arguments that ``request`` takes.
  38. """
  39. kwargs.setdefault('allow_redirects', True)
  40. return request('get', url, **kwargs)
  41. def options(url, **kwargs):
  42. """Sends a OPTIONS request. Returns :class:`Response` object.
  43. :param url: URL for the new :class:`Request` object.
  44. :param \*\*kwargs: Optional arguments that ``request`` takes.
  45. """
  46. kwargs.setdefault('allow_redirects', True)
  47. return request('options', url, **kwargs)
  48. def head(url, **kwargs):
  49. """Sends a HEAD request. Returns :class:`Response` object.
  50. :param url: URL for the new :class:`Request` object.
  51. :param \*\*kwargs: Optional arguments that ``request`` takes.
  52. """
  53. kwargs.setdefault('allow_redirects', False)
  54. return request('head', url, **kwargs)
  55. def post(url, data=None, **kwargs):
  56. """Sends a POST request. Returns :class:`Response` object.
  57. :param url: URL for the new :class:`Request` object.
  58. :param data: (optional) Dictionary, bytes, or file-like object to send in the body of the :class:`Request`.
  59. :param \*\*kwargs: Optional arguments that ``request`` takes.
  60. """
  61. return request('post', url, data=data, **kwargs)
  62. def put(url, data=None, **kwargs):
  63. """Sends a PUT request. Returns :class:`Response` object.
  64. :param url: URL for the new :class:`Request` object.
  65. :param data: (optional) Dictionary, bytes, or file-like object to send in the body of the :class:`Request`.
  66. :param \*\*kwargs: Optional arguments that ``request`` takes.
  67. """
  68. return request('put', url, data=data, **kwargs)
  69. def patch(url, data=None, **kwargs):
  70. """Sends a PATCH request. Returns :class:`Response` object.
  71. :param url: URL for the new :class:`Request` object.
  72. :param data: (optional) Dictionary, bytes, or file-like object to send in the body of the :class:`Request`.
  73. :param \*\*kwargs: Optional arguments that ``request`` takes.
  74. """
  75. return request('patch', url, data=data, **kwargs)
  76. def delete(url, **kwargs):
  77. """Sends a DELETE request. Returns :class:`Response` object.
  78. :param url: URL for the new :class:`Request` object.
  79. :param \*\*kwargs: Optional arguments that ``request`` takes.
  80. """
  81. return request('delete', url, **kwargs)