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