python (3.11.7)
1 """
2 requests.api
3 ~~~~~~~~~~~~
4
5 This module implements the Requests API.
6
7 :copyright: (c) 2012 by Kenneth Reitz.
8 :license: Apache2, see LICENSE for more details.
9 """
10
11 from . import sessions
12
13
14 def request(method, url, **kwargs):
15 """Constructs and sends a :class:`Request <Request>`.
16
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
30 to add for the file.
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
46
47 Usage::
48
49 >>> import requests
50 >>> req = requests.request('GET', 'https://httpbin.org/get')
51 >>> req
52 <Response [200]>
53 """
54
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)
60
61
62 def get(url, params=None, **kwargs):
63 r"""Sends a GET request.
64
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
71 """
72
73 return request("get", url, params=params, **kwargs)
74
75
76 def options(url, **kwargs):
77 r"""Sends an OPTIONS request.
78
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
83 """
84
85 return request("options", url, **kwargs)
86
87
88 def head(url, **kwargs):
89 r"""Sends a HEAD request.
90
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
97 """
98
99 kwargs.setdefault("allow_redirects", False)
100 return request("head", url, **kwargs)
101
102
103 def post(url, data=None, json=None, **kwargs):
104 r"""Sends a POST request.
105
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
113 """
114
115 return request("post", url, data=data, json=json, **kwargs)
116
117
118 def put(url, data=None, **kwargs):
119 r"""Sends a PUT request.
120
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
128 """
129
130 return request("put", url, data=data, **kwargs)
131
132
133 def patch(url, data=None, **kwargs):
134 r"""Sends a PATCH request.
135
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
143 """
144
145 return request("patch", url, data=data, **kwargs)
146
147
148 def delete(url, **kwargs):
149 r"""Sends a DELETE request.
150
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
155 """
156
157 return request("delete", url, **kwargs)
Browse
Usage
Versions