5
This module implements the Requests API.
7
:copyright: (c) 2012 by Kenneth Reitz.
8
:license: Apache2, see LICENSE for more details.
11
from __future__ import annotations
13
from typing import TYPE_CHECKING
16
from .models import Response
19
from typing_extensions import Unpack
21
from . import _types as _t
25
method: str, url: _t.UriType, **kwargs: Unpack[_t.RequestKwargs]
27
"""Constructs and sends a :class:`Request <Request>`.
29
:param method: method for the new :class:`Request` object: ``GET``, ``OPTIONS``, ``HEAD``, ``POST``, ``PUT``, ``PATCH``, or ``DELETE``.
30
:param url: URL for the new :class:`Request` object.
31
:param params: (optional) Dictionary, list of tuples or bytes to send
32
in the query string for the :class:`Request`.
33
:param data: (optional) Dictionary, list of tuples, bytes, or file-like
34
object to send in the body of the :class:`Request`.
35
:param json: (optional) A JSON serializable Python object to send in the body of the :class:`Request`.
36
:param headers: (optional) Dictionary of HTTP Headers to send with the :class:`Request`.
37
:param cookies: (optional) Dict or CookieJar object to send with the :class:`Request`.
38
:param files: (optional) Dictionary of ``'name': file-like-objects`` (or ``{'name': file-tuple}``) for multipart encoding upload.
39
``file-tuple`` can be a 2-tuple ``('filename', fileobj)``, 3-tuple ``('filename', fileobj, 'content_type')``
40
or a 4-tuple ``('filename', fileobj, 'content_type', custom_headers)``, where ``'content_type'`` is a string
41
defining the content type of the given file and ``custom_headers`` a dict-like object containing additional headers
43
:param auth: (optional) Auth tuple to enable Basic/Digest/Custom HTTP Auth.
44
:param timeout: (optional) How many seconds to wait for the server to send data
45
before giving up, as a float, or a :ref:`(connect timeout, read
46
timeout) <timeouts>` tuple.
47
:type timeout: float or tuple
48
:param allow_redirects: (optional) Boolean. Enable/disable GET/OPTIONS/POST/PUT/PATCH/DELETE/HEAD redirection. Defaults to ``True``.
49
:type allow_redirects: bool
50
:param proxies: (optional) Dictionary mapping protocol to the URL of the proxy.
51
:param verify: (optional) Either a boolean, in which case it controls whether we verify
52
the server's TLS certificate, or a string, in which case it must be a path
53
to a CA bundle to use. Defaults to ``True``.
54
:param stream: (optional) if ``False``, the response content will be immediately downloaded.
55
:param cert: (optional) if String, path to ssl client cert file (.pem). If Tuple, ('cert', 'key') pair.
56
:return: :class:`Response <Response>` object
57
:rtype: requests.Response
53
to a CA bundle to use. Defaults to ``True``.
54
:param stream: (optional) if ``False``, the response content will be immediately downloaded.
55
:param cert: (optional) if String, path to ssl client cert file (.pem). If Tuple, ('cert', 'key') pair.
56
:return: :class:`Response <Response>` object
57
:rtype: requests.Response
62
>>> req = requests.request('GET', 'https://httpbin.org/get')
67
# By using the 'with' statement we are sure the session is closed, thus we
68
# avoid leaving sockets open which can trigger a ResourceWarning in some
69
# cases, and look like a memory leak in others.
70
with sessions.Session() as session:
71
return session.request(method=method, url=url, **kwargs)
75
url: _t.UriType, params: _t.ParamsType = None, **kwargs: Unpack[_t.GetKwargs]
77
r"""Sends a GET request.
79
:param url: URL for the new :class:`Request` object.
80
:param params: (optional) Dictionary, list of tuples or bytes to send
81
in the query string for the :class:`Request`.
82
:param \*\*kwargs: Optional arguments that ``request`` takes.
83
:return: :class:`Response <Response>` object
84
:rtype: requests.Response
87
return request("get", url, params=params, **kwargs)
90
def options(url: _t.UriType, **kwargs: Unpack[_t.RequestKwargs]) -> Response:
91
r"""Sends an OPTIONS request.
87
return request("get", url, params=params, **kwargs)
90
def options(url: _t.UriType, **kwargs: Unpack[_t.RequestKwargs]) -> Response:
91
r"""Sends an OPTIONS request.
93
:param url: URL for the new :class:`Request` object.
94
:param \*\*kwargs: Optional arguments that ``request`` takes.
95
:return: :class:`Response <Response>` object
96
:rtype: requests.Response
99
return request("options", url, **kwargs)
102
def head(url: _t.UriType, **kwargs: Unpack[_t.RequestKwargs]) -> Response:
103
r"""Sends a HEAD request.
105
:param url: URL for the new :class:`Request` object.
106
:param \*\*kwargs: Optional arguments that ``request`` takes. If
107
`allow_redirects` is not provided, it will be set to `False` (as
108
opposed to the default :meth:`request` behavior).
109
:return: :class:`Response <Response>` object
110
:rtype: requests.Response
113
kwargs.setdefault("allow_redirects", False)
114
return request("head", url, **kwargs)
119
data: _t.DataType = None,
120
json: _t.JsonType = None,
121
**kwargs: Unpack[_t.PostKwargs],
123
r"""Sends a POST request.
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) A JSON serializable Python object 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
128
:param json: (optional) A JSON serializable Python object 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
134
return request("post", url, data=data, json=json, **kwargs)
138
url: _t.UriType, data: _t.DataType = None, **kwargs: Unpack[_t.DataKwargs]
140
r"""Sends a PUT request.
142
:param url: URL for the new :class:`Request` object.
143
:param data: (optional) Dictionary, list of tuples, bytes, or file-like
144
object to send in the body of the :class:`Request`.
145
:param json: (optional) A JSON serializable Python object to send in the body of the :class:`Request`.
146
:param \*\*kwargs: Optional arguments that ``request`` takes.
147
:return: :class:`Response <Response>` object
148
:rtype: requests.Response
151
return request("put", url, data=data, **kwargs)
155
url: _t.UriType, data: _t.DataType = None, **kwargs: Unpack[_t.DataKwargs]
157
r"""Sends a PATCH request.
159
:param url: URL for the new :class:`Request` object.
160
:param data: (optional) Dictionary, list of tuples, bytes, or file-like
161
object to send in the body of the :class:`Request`.
162
:param json: (optional) A JSON serializable Python object to send in the body of the :class:`Request`.
163
:param \*\*kwargs: Optional arguments that ``request`` takes.
164
:return: :class:`Response <Response>` object
165
:rtype: requests.Response
162
:param json: (optional) A JSON serializable Python object to send in the body of the :class:`Request`.
163
:param \*\*kwargs: Optional arguments that ``request`` takes.
164
:return: :class:`Response <Response>` object
165
:rtype: requests.Response
168
return request("patch", url, data=data, **kwargs)
171
def delete(url: _t.UriType, **kwargs: Unpack[_t.RequestKwargs]) -> Response:
172
r"""Sends a DELETE request.
174
:param url: URL for the new :class:`Request` object.
175
:param \*\*kwargs: Optional arguments that ``request`` takes.
176
:return: :class:`Response <Response>` object
177
:rtype: requests.Response
180
return request("delete", url, **kwargs)