Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.8/site-packages/urllib3/util/timeout.py: 36%

1from __future__ import absolute_import 

2 

3import time 

4 

5# The default socket timeout, used by httplib to indicate that no timeout was; specified by the user 

6from socket import _GLOBAL_DEFAULT_TIMEOUT, getdefaulttimeout 

7 

8from ..exceptions import TimeoutStateError 

9 

10# A sentinel value to indicate that no timeout was specified by the user in 

11# urllib3 

12_Default = object() 

13 

14 

15# Use time.monotonic if available. 

16current_time = getattr(time, "monotonic", time.time) 

17 

18 

19class Timeout(object): 

20 """Timeout configuration. 

21 

22 Timeouts can be defined as a default for a pool: 

23 

24 .. code-block:: python 

25 

26 timeout = Timeout(connect=2.0, read=7.0) 

27 http = PoolManager(timeout=timeout) 

28 response = http.request('GET', 'http://example.com/') 

29 

30 Or per-request (which overrides the default for the pool): 

31 

32 .. code-block:: python 

33 

34 response = http.request('GET', 'http://example.com/', timeout=Timeout(10)) 

35 

36 Timeouts can be disabled by setting all the parameters to ``None``: 

37 

38 .. code-block:: python 

39 

40 no_timeout = Timeout(connect=None, read=None) 

41 response = http.request('GET', 'http://example.com/, timeout=no_timeout) 

42 

43 

44 :param total: 

45 This combines the connect and read timeouts into one; the read timeout 

46 will be set to the time leftover from the connect attempt. In the 

47 event that both a connect timeout and a total are specified, or a read 

48 timeout and a total are specified, the shorter timeout will be applied. 

49 

50 Defaults to None. 

51 

52 :type total: int, float, or None 

53 

54 :param connect: 

55 The maximum amount of time (in seconds) to wait for a connection 

56 attempt to a server to succeed. Omitting the parameter will default the 

57 connect timeout to the system default, probably `the global default 

58 timeout in socket.py 

59 <http://hg.python.org/cpython/file/603b4d593758/Lib/socket.py#l535>`_. 

60 None will set an infinite timeout for connection attempts. 

61 

62 :type connect: int, float, or None 

63 

64 :param read: 

65 The maximum amount of time (in seconds) to wait between consecutive 

66 read operations for a response from the server. Omitting the parameter 

67 will default the read timeout to the system default, probably `the 

68 global default timeout in socket.py 

69 <http://hg.python.org/cpython/file/603b4d593758/Lib/socket.py#l535>`_. 

70 None will set an infinite timeout. 

71 

72 :type read: int, float, or None 

73 

74 .. note:: 

75 

76 Many factors can affect the total amount of time for urllib3 to return 

77 an HTTP response. 

78 

79 For example, Python's DNS resolver does not obey the timeout specified 

80 on the socket. Other factors that can affect total request time include 

81 high CPU load, high swap, the program running at a low priority level, 

82 or other behaviors. 

83 

84 In addition, the read and total timeouts only measure the time between 

85 read operations on the socket connecting the client and the server, 

86 not the total amount of time for the request to return a complete 

87 response. For most requests, the timeout is raised because the server 

88 has not sent the first byte in the specified time. This is not always 

89 the case; if a server streams one byte every fifteen seconds, a timeout 

90 of 20 seconds will not trigger, even though the request will take 

91 several minutes to complete. 

92 

93 If your goal is to cut off any request after a set amount of wall clock 

94 time, consider having a second "watcher" thread to cut off a slow 

95 request. 

96 """ 

97 

98 #: A sentinel object representing the default timeout value 

99 DEFAULT_TIMEOUT = _GLOBAL_DEFAULT_TIMEOUT 

100 

101 def __init__(self, total=None, connect=_Default, read=_Default): 

102 self._connect = self._validate_timeout(connect, "connect") 

103 self._read = self._validate_timeout(read, "read") 

104 self.total = self._validate_timeout(total, "total") 

105 self._start_connect = None 

106 

107 def __repr__(self): 

108 return "%s(connect=%r, read=%r, total=%r)" % ( 

109 type(self).__name__, 

110 self._connect, 

111 self._read, 

112 self.total, 

113 ) 

114 

115 # __str__ provided for backwards compatibility 

116 __str__ = __repr__ 

117 

118 @classmethod 

119 def resolve_default_timeout(cls, timeout): 

120 return getdefaulttimeout() if timeout is cls.DEFAULT_TIMEOUT else timeout 

121 

122 @classmethod 

123 def _validate_timeout(cls, value, name): 

124 """Check that a timeout attribute is valid. 

125 

126 :param value: The timeout value to validate 

127 :param name: The name of the timeout attribute to validate. This is 

128 used to specify in error messages. 

129 :return: The validated and casted version of the given value. 

130 :raises ValueError: If it is a numeric value less than or equal to 

131 zero, or the type is not an integer, float, or None. 

132 """ 

133 if value is _Default: 

134 return cls.DEFAULT_TIMEOUT 

135 

136 if value is None or value is cls.DEFAULT_TIMEOUT: 

137 return value 

138 

139 if isinstance(value, bool): 

140 raise ValueError( 

141 "Timeout cannot be a boolean value. It must " 

142 "be an int, float or None." 

143 ) 

144 try: 

145 float(value) 

146 except (TypeError, ValueError): 

147 raise ValueError( 

148 "Timeout value %s was %s, but it must be an " 

149 "int, float or None." % (name, value) 

150 ) 

151 

152 try: 

153 if value <= 0: 

154 raise ValueError( 

155 "Attempted to set %s timeout to %s, but the " 

156 "timeout cannot be set to a value less " 

157 "than or equal to 0." % (name, value) 

158 ) 

159 except TypeError: 

160 # Python 3 

161 raise ValueError( 

162 "Timeout value %s was %s, but it must be an " 

163 "int, float or None." % (name, value) 

164 ) 

165 

166 return value 

167 

168 @classmethod 

169 def from_float(cls, timeout): 

170 """Create a new Timeout from a legacy timeout value. 

171 

172 The timeout value used by httplib.py sets the same timeout on the 

173 connect(), and recv() socket requests. This creates a :class:`Timeout` 

174 object that sets the individual timeouts to the ``timeout`` value 

175 passed to this function. 

176 

177 :param timeout: The legacy timeout value. 

178 :type timeout: integer, float, sentinel default object, or None 

179 :return: Timeout object 

180 :rtype: :class:`Timeout` 

181 """ 

182 return Timeout(read=timeout, connect=timeout) 

183 

184 def clone(self): 

185 """Create a copy of the timeout object 

186 

187 Timeout properties are stored per-pool but each request needs a fresh 

188 Timeout object to ensure each one has its own start/stop configured. 

189 

190 :return: a copy of the timeout object 

191 :rtype: :class:`Timeout` 

192 """ 

193 # We can't use copy.deepcopy because that will also create a new object 

194 # for _GLOBAL_DEFAULT_TIMEOUT, which socket.py uses as a sentinel to 

195 # detect the user default. 

196 return Timeout(connect=self._connect, read=self._read, total=self.total) 

197 

198 def start_connect(self): 

199 """Start the timeout clock, used during a connect() attempt 

200 

201 :raises urllib3.exceptions.TimeoutStateError: if you attempt 

202 to start a timer that has been started already. 

203 """ 

204 if self._start_connect is not None: 

205 raise TimeoutStateError("Timeout timer has already been started.") 

206 self._start_connect = current_time() 

207 return self._start_connect 

208 

209 def get_connect_duration(self): 

210 """Gets the time elapsed since the call to :meth:`start_connect`. 

211 

212 :return: Elapsed time in seconds. 

213 :rtype: float 

214 :raises urllib3.exceptions.TimeoutStateError: if you attempt 

215 to get duration for a timer that hasn't been started. 

216 """ 

217 if self._start_connect is None: 

218 raise TimeoutStateError( 

219 "Can't get connect duration for timer that has not started." 

220 ) 

221 return current_time() - self._start_connect 

222 

223 @property 

224 def connect_timeout(self): 

225 """Get the value to use when setting a connection timeout. 

226 

227 This will be a positive float or integer, the value None 

228 (never timeout), or the default system timeout. 

229 

230 :return: Connect timeout. 

231 :rtype: int, float, :attr:`Timeout.DEFAULT_TIMEOUT` or None 

232 """ 

233 if self.total is None: 

234 return self._connect 

235 

236 if self._connect is None or self._connect is self.DEFAULT_TIMEOUT: 

237 return self.total 

238 

239 return min(self._connect, self.total) 

240 

241 @property 

242 def read_timeout(self): 

243 """Get the value for the read timeout. 

244 

245 This assumes some time has elapsed in the connection timeout and 

246 computes the read timeout appropriately. 

247 

248 If self.total is set, the read timeout is dependent on the amount of 

249 time taken by the connect timeout. If the connection time has not been 

250 established, a :exc:`~urllib3.exceptions.TimeoutStateError` will be 

251 raised. 

252 

253 :return: Value to use for the read timeout. 

254 :rtype: int, float, :attr:`Timeout.DEFAULT_TIMEOUT` or None 

255 :raises urllib3.exceptions.TimeoutStateError: If :meth:`start_connect` 

256 has not yet been called on this object. 

257 """ 

258 if ( 

259 self.total is not None 

260 and self.total is not self.DEFAULT_TIMEOUT 

261 and self._read is not None 

262 and self._read is not self.DEFAULT_TIMEOUT 

263 ): 

264 # In case the connect timeout has not yet been established. 

265 if self._start_connect is None: 

266 return self._read 

267 return max(0, min(self.total - self.get_connect_duration(), self._read)) 

268 elif self.total is not None and self.total is not self.DEFAULT_TIMEOUT: 

269 return max(0, self.total - self.get_connect_duration()) 

270 else: 

271 return self._read