Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.8/site-packages/urllib3/__init__.py: 69%

1""" 

2Python HTTP library with thread-safe connection pooling, file post support, user friendly, and more 

3""" 

4 

5from __future__ import annotations 

6 

7# Set default logging handler to avoid "No handler found" warnings. 

8import logging 

9import sys 

10import typing 

11import warnings 

12from logging import NullHandler 

13 

14from . import exceptions 

15from ._base_connection import _TYPE_BODY 

16from ._collections import HTTPHeaderDict 

17from ._version import __version__ 

18from .connectionpool import HTTPConnectionPool, HTTPSConnectionPool, connection_from_url 

19from .filepost import _TYPE_FIELDS, encode_multipart_formdata 

20from .poolmanager import PoolManager, ProxyManager, proxy_from_url 

21from .response import BaseHTTPResponse, HTTPResponse 

22from .util.request import make_headers 

23from .util.retry import Retry 

24from .util.timeout import Timeout 

25 

26# Ensure that Python is compiled with OpenSSL 1.1.1+ 

27# If the 'ssl' module isn't available at all that's 

28# fine, we only care if the module is available. 

29try: 

30 import ssl 

31except ImportError: 

32 pass 

33else: 

34 if not ssl.OPENSSL_VERSION.startswith("OpenSSL "): # Defensive: 

35 warnings.warn( 

36 "urllib3 v2 only supports OpenSSL 1.1.1+, currently " 

37 f"the 'ssl' module is compiled with {ssl.OPENSSL_VERSION!r}. " 

38 "See: https://github.com/urllib3/urllib3/issues/3020", 

39 exceptions.NotOpenSSLWarning, 

40 ) 

41 elif ssl.OPENSSL_VERSION_INFO < (1, 1, 1): # Defensive: 

42 raise ImportError( 

43 "urllib3 v2 only supports OpenSSL 1.1.1+, currently " 

44 f"the 'ssl' module is compiled with {ssl.OPENSSL_VERSION!r}. " 

45 "See: https://github.com/urllib3/urllib3/issues/2168" 

46 ) 

47 

48__author__ = "Andrey Petrov (andrey.petrov@shazow.net)" 

49__license__ = "MIT" 

50__version__ = __version__ 

51 

52__all__ = ( 

53 "HTTPConnectionPool", 

54 "HTTPHeaderDict", 

55 "HTTPSConnectionPool", 

56 "PoolManager", 

57 "ProxyManager", 

58 "HTTPResponse", 

59 "Retry", 

60 "Timeout", 

61 "add_stderr_logger", 

62 "connection_from_url", 

63 "disable_warnings", 

64 "encode_multipart_formdata", 

65 "make_headers", 

66 "proxy_from_url", 

67 "request", 

68 "BaseHTTPResponse", 

69) 

70 

71logging.getLogger(__name__).addHandler(NullHandler()) 

72 

73 

74def add_stderr_logger( 

75 level: int = logging.DEBUG, 

76) -> logging.StreamHandler[typing.TextIO]: 

77 """ 

78 Helper for quickly adding a StreamHandler to the logger. Useful for 

79 debugging. 

80 

81 Returns the handler after adding it. 

82 """ 

83 # This method needs to be in this __init__.py to get the __name__ correct 

84 # even if urllib3 is vendored within another package. 

85 logger = logging.getLogger(__name__) 

86 handler = logging.StreamHandler() 

87 handler.setFormatter(logging.Formatter("%(asctime)s %(levelname)s %(message)s")) 

88 logger.addHandler(handler) 

89 logger.setLevel(level) 

90 logger.debug("Added a stderr logging handler to logger: %s", __name__) 

91 return handler 

92 

93 

94# ... Clean up. 

95del NullHandler 

96 

97 

98# All warning filters *must* be appended unless you're really certain that they 

99# shouldn't be: otherwise, it's very hard for users to use most Python 

100# mechanisms to silence them. 

101# SecurityWarning's always go off by default. 

102warnings.simplefilter("always", exceptions.SecurityWarning, append=True) 

103# InsecurePlatformWarning's don't vary between requests, so we keep it default. 

104warnings.simplefilter("default", exceptions.InsecurePlatformWarning, append=True) 

105 

106 

107def disable_warnings(category: type[Warning] = exceptions.HTTPWarning) -> None: 

108 """ 

109 Helper for quickly disabling all urllib3 warnings. 

110 """ 

111 warnings.simplefilter("ignore", category) 

112 

113 

114_DEFAULT_POOL = PoolManager() 

115 

116 

117def request( 

118 method: str, 

119 url: str, 

120 *, 

121 body: _TYPE_BODY | None = None, 

122 fields: _TYPE_FIELDS | None = None, 

123 headers: typing.Mapping[str, str] | None = None, 

124 preload_content: bool | None = True, 

125 decode_content: bool | None = True, 

126 redirect: bool | None = True, 

127 retries: Retry | bool | int | None = None, 

128 timeout: Timeout | float | int | None = 3, 

129 json: typing.Any | None = None, 

130) -> BaseHTTPResponse: 

131 """ 

132 A convenience, top-level request method. It uses a module-global ``PoolManager`` instance. 

133 Therefore, its side effects could be shared across dependencies relying on it. 

134 To avoid side effects create a new ``PoolManager`` instance and use it instead. 

135 The method does not accept low-level ``**urlopen_kw`` keyword arguments. 

136 

137 :param method: 

138 HTTP request method (such as GET, POST, PUT, etc.) 

139 

140 :param url: 

141 The URL to perform the request on. 

142 

143 :param body: 

144 Data to send in the request body, either :class:`str`, :class:`bytes`, 

145 an iterable of :class:`str`/:class:`bytes`, or a file-like object. 

146 

147 :param fields: 

148 Data to encode and send in the request body. 

149 

150 :param headers: 

151 Dictionary of custom headers to send, such as User-Agent, 

152 If-None-Match, etc. 

153 

154 :param bool preload_content: 

155 If True, the response's body will be preloaded into memory. 

156 

157 :param bool decode_content: 

158 If True, will attempt to decode the body based on the 

159 'content-encoding' header. 

160 

161 :param redirect: 

162 If True, automatically handle redirects (status codes 301, 302, 

163 303, 307, 308). Each redirect counts as a retry. Disabling retries 

164 will disable redirect, too. 

165 

166 :param retries: 

167 Configure the number of retries to allow before raising a 

168 :class:`~urllib3.exceptions.MaxRetryError` exception. 

169 

170 If ``None`` (default) will retry 3 times, see ``Retry.DEFAULT``. Pass a 

171 :class:`~urllib3.util.retry.Retry` object for fine-grained control 

172 over different types of retries. 

173 Pass an integer number to retry connection errors that many times, 

174 but no other types of errors. Pass zero to never retry. 

175 

176 If ``False``, then retries are disabled and any exception is raised 

177 immediately. Also, instead of raising a MaxRetryError on redirects, 

178 the redirect response will be returned. 

179 

180 :type retries: :class:`~urllib3.util.retry.Retry`, False, or an int. 

181 

182 :param timeout: 

183 If specified, overrides the default timeout for this one 

184 request. It may be a float (in seconds) or an instance of 

185 :class:`urllib3.util.Timeout`. 

186 

187 :param json: 

188 Data to encode and send as JSON with UTF-encoded in the request body. 

189 The ``"Content-Type"`` header will be set to ``"application/json"`` 

190 unless specified otherwise. 

191 """ 

192 

193 return _DEFAULT_POOL.request( 

194 method, 

195 url, 

196 body=body, 

197 fields=fields, 

198 headers=headers, 

199 preload_content=preload_content, 

200 decode_content=decode_content, 

201 redirect=redirect, 

202 retries=retries, 

203 timeout=timeout, 

204 json=json, 

205 ) 

206 

207 

208if sys.platform == "emscripten": 

209 from .contrib.emscripten import inject_into_urllib3 # noqa: 401 

210 

211 inject_into_urllib3()