Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.11/site-packages/requests/api.py: 54%

1""" 

2requests.api 

3~~~~~~~~~~~~ 

4 

5This module implements the Requests API. 

6 

7:copyright: (c) 2012 by Kenneth Reitz. 

8:license: Apache2, see LICENSE for more details. 

9""" 

10 

11from __future__ import annotations 

12 

13from typing import TYPE_CHECKING 

14 

15from . import sessions 

16from .models import Response 

17 

18if TYPE_CHECKING: 

19 from typing_extensions import Unpack 

20 

21 from . import _types as _t 

22 

23 

24def request( 

25 method: str, url: _t.UriType, **kwargs: Unpack[_t.RequestKwargs] 

26) -> Response: 

27 """Constructs and sends a :class:`Request <Request>`. 

28 

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 

42 to add for the file. 

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 

58 

59 Usage:: 

60 

61 >>> import requests 

62 >>> req = requests.request('GET', 'https://httpbin.org/get') 

63 >>> req 

64 <Response [200]> 

65 """ 

66 

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) 

72 

73 

74def get( 

75 url: _t.UriType, params: _t.ParamsType = None, **kwargs: Unpack[_t.GetKwargs] 

76) -> Response: 

77 r"""Sends a GET request. 

78 

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 

85 """ 

86 

87 return request("get", url, params=params, **kwargs) 

88 

89 

90def options(url: _t.UriType, **kwargs: Unpack[_t.RequestKwargs]) -> Response: 

91 r"""Sends an OPTIONS request. 

92 

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 

97 """ 

98 

99 return request("options", url, **kwargs) 

100 

101 

102def head(url: _t.UriType, **kwargs: Unpack[_t.RequestKwargs]) -> Response: 

103 r"""Sends a HEAD request. 

104 

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 

111 """ 

112 

113 kwargs.setdefault("allow_redirects", False) 

114 return request("head", url, **kwargs) 

115 

116 

117def post( 

118 url: _t.UriType, 

119 data: _t.DataType = None, 

120 json: _t.JsonType = None, 

121 **kwargs: Unpack[_t.PostKwargs], 

122) -> Response: 

123 r"""Sends a POST 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) 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 

132 """ 

133 

134 return request("post", url, data=data, json=json, **kwargs) 

135 

136 

137def put( 

138 url: _t.UriType, data: _t.DataType = None, **kwargs: Unpack[_t.DataKwargs] 

139) -> Response: 

140 r"""Sends a PUT request. 

141 

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 

149 """ 

150 

151 return request("put", url, data=data, **kwargs) 

152 

153 

154def patch( 

155 url: _t.UriType, data: _t.DataType = None, **kwargs: Unpack[_t.DataKwargs] 

156) -> Response: 

157 r"""Sends a PATCH request. 

158 

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 

166 """ 

167 

168 return request("patch", url, data=data, **kwargs) 

169 

170 

171def delete(url: _t.UriType, **kwargs: Unpack[_t.RequestKwargs]) -> Response: 

172 r"""Sends a DELETE request. 

173 

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 

178 """ 

179 

180 return request("delete", url, **kwargs)