1# -*- coding: utf-8 -*- 2 3""" 4requests.api 5~~~~~~~~~~~~ 6 7This module implements the Requests API. 8 9:copyright: (c) 2012 by Kenneth Reitz. 10:license: Apache2, see LICENSE for more details. 11""" 12 13from . import sessions 14 15 16def request(method, url, **kwargs): 17 """Constructs and sends a :class:`Request <Request>`. 18 19 :param method: method for the new :class:`Request` object: ``GET``, ``OPTIONS``, ``HEAD``, ``POST``, ``PUT``, ``PATCH``, or ``DELETE``. 20 :param url: URL for the new :class:`Request` object. 21 :param params: (optional) Dictionary, list of tuples or bytes to send 22 in the query string for the :class:`Request`. 23 :param data: (optional) Dictionary, list of tuples, bytes, or file-like 24 object to send in the body of the :class:`Request`. 25 :param json: (optional) A JSON serializable Python object to send in the body of the :class:`Request`. 26 :param headers: (optional) Dictionary of HTTP Headers to send with the :class:`Request`. 27 :param cookies: (optional) Dict or CookieJar object to send with the :class:`Request`. 28 :param files: (optional) Dictionary of ``'name': file-like-objects`` (or ``{'name': file-tuple}``) for multipart encoding upload. 29 ``file-tuple`` can be a 2-tuple ``('filename', fileobj)``, 3-tuple ``('filename', fileobj, 'content_type')`` 30 or a 4-tuple ``('filename', fileobj, 'content_type', custom_headers)``, where ``'content-type'`` is a string 31 defining the content type of the given file and ``custom_headers`` a dict-like object containing additional headers 32 to add for the file. 33 :param auth: (optional) Auth tuple to enable Basic/Digest/Custom HTTP Auth. 34 :param timeout: (optional) How many seconds to wait for the server to send data 35 before giving up, as a float, or a :ref:`(connect timeout, read 36 timeout) <timeouts>` tuple. 37 :type timeout: float or tuple 38 :param allow_redirects: (optional) Boolean. Enable/disable GET/OPTIONS/POST/PUT/PATCH/DELETE/HEAD redirection. Defaults to ``True``. 39 :type allow_redirects: bool 40 :param proxies: (optional) Dictionary mapping protocol to the URL of the proxy. 41 :param verify: (optional) Either a boolean, in which case it controls whether we verify 42 the server's TLS certificate, or a string, in which case it must be a path 43 to a CA bundle to use. Defaults to ``True``. 44 :param stream: (optional) if ``False``, the response content will be immediately downloaded. 45 :param cert: (optional) if String, path to ssl client cert file (.pem). If Tuple, ('cert', 'key') pair. 46 :return: :class:`Response <Response>` object 47 :rtype: requests.Response 48 49 Usage:: 50 51 >>> import requests 52 >>> req = requests.request('GET', 'https://httpbin.org/get') 53 >>> req 54 <Response [200]> 55 """ 56 57 # By using the 'with' statement we are sure the session is closed, thus we 58 # avoid leaving sockets open which can trigger a ResourceWarning in some 59 # cases, and look like a memory leak in others. 60 with sessions.Session() as session: 61 return session.request(method=method, url=url, **kwargs) 62 63 64def get(url, params=None, **kwargs): 65 r"""Sends a GET request. 66 67 :param url: URL for the new :class:`Request` object. 68 :param params: (optional) Dictionary, list of tuples or bytes to send 69 in the query string for the :class:`Request`. 70 :param \*\*kwargs: Optional arguments that ``request`` takes. 71 :return: :class:`Response <Response>` object 72 :rtype: requests.Response 73 """ 74 75 kwargs.setdefault('allow_redirects', True) 76 return request('get', url, params=params, **kwargs) 77 78 79def options(url, **kwargs): 80 r"""Sends an OPTIONS request. 81 82 :param url: URL for the new :class:`Request` object. 83 :param \*\*kwargs: Optional arguments that ``request`` takes. 84 :return: :class:`Response <Response>` object 85 :rtype: requests.Response 86 """ 87 88 kwargs.setdefault('allow_redirects', True) 89 return request('options', url, **kwargs) 90 91 92def head(url, **kwargs): 93 r"""Sends a HEAD request. 94 95 :param url: URL for the new :class:`Request` object. 96 :param \*\*kwargs: Optional arguments that ``request`` takes. If 97 `allow_redirects` is not provided, it will be set to `False` (as 98 opposed to the default :meth:`request` behavior). 99 :return: :class:`Response <Response>` object 100 :rtype: requests.Response 101 """ 102 103 kwargs.setdefault('allow_redirects', False) 104 return request('head', url, **kwargs) 105 106 107def post(url, data=None, json=None, **kwargs): 108 r"""Sends a POST request. 109 110 :param url: URL for the new :class:`Request` object. 111 :param data: (optional) Dictionary, list of tuples, bytes, or file-like 112 object to send in the body of the :class:`Request`. 113 :param json: (optional) json data to send in the body of the :class:`Request`. 114 :param \*\*kwargs: Optional arguments that ``request`` takes. 115 :return: :class:`Response <Response>` object 116 :rtype: requests.Response 117 """ 118 119 return request('post', url, data=data, json=json, **kwargs) 120 121 122def put(url, data=None, **kwargs): 123 r"""Sends a PUT request. 124 125 :param url: URL for the new :class:`Request` object. 126 :param data: (optional) Dictionary, list of tuples, bytes, or file-like 127 object to send in the body of the :class:`Request`. 128 :param json: (optional) json data to send in the body of the :class:`Request`. 129 :param \*\*kwargs: Optional arguments that ``request`` takes. 130 :return: :class:`Response <Response>` object 131 :rtype: requests.Response 132 """ 133 134 return request('put', url, data=data, **kwargs) 135 136 137def patch(url, data=None, **kwargs): 138 r"""Sends a PATCH request. 139 140 :param url: URL for the new :class:`Request` object. 141 :param data: (optional) Dictionary, list of tuples, bytes, or file-like 142 object to send in the body of the :class:`Request`. 143 :param json: (optional) json data to send in the body of the :class:`Request`. 144 :param \*\*kwargs: Optional arguments that ``request`` takes. 145 :return: :class:`Response <Response>` object 146 :rtype: requests.Response 147 """ 148 149 return request('patch', url, data=data, **kwargs) 150 151 152def delete(url, **kwargs): 153 r"""Sends a DELETE request. 154 155 :param url: URL for the new :class:`Request` object. 156 :param \*\*kwargs: Optional arguments that ``request`` takes. 157 :return: :class:`Response <Response>` object 158 :rtype: requests.Response 159 """ 160 161 return request('delete', url, **kwargs) 162