Hide keyboard shortcuts

Hot-keys on this page

r m x p   toggle line displays

j k   next/prev highlighted chunk

0   (zero) top of page

1   (one) first highlighted chunk

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)