1import ssl 2import sys 3from _typeshed import StrOrBytesPath 4from email.message import Message 5from http.client import HTTPMessage, HTTPResponse, _HTTPConnectionProtocol 6from http.cookiejar import CookieJar 7from typing import ( 8 IO, 9 Any, 10 Callable, 11 ClassVar, 12 Dict, 13 List, 14 Mapping, 15 NoReturn, 16 Optional, 17 Pattern, 18 Sequence, 19 Tuple, 20 TypeVar, 21 Union, 22 overload, 23) 24from urllib.error import HTTPError 25from urllib.response import addclosehook, addinfourl 26 27_T = TypeVar("_T") 28_UrlopenRet = Any 29 30def urlopen( 31 url: Union[str, Request], 32 data: Optional[bytes] = ..., 33 timeout: Optional[float] = ..., 34 *, 35 cafile: Optional[str] = ..., 36 capath: Optional[str] = ..., 37 cadefault: bool = ..., 38 context: Optional[ssl.SSLContext] = ..., 39) -> _UrlopenRet: ... 40def install_opener(opener: OpenerDirector) -> None: ... 41def build_opener(*handlers: Union[BaseHandler, Callable[[], BaseHandler]]) -> OpenerDirector: ... 42 43if sys.platform == "win32": 44 from nturl2path import pathname2url as pathname2url, url2pathname as url2pathname 45else: 46 def url2pathname(pathname: str) -> str: ... 47 def pathname2url(pathname: str) -> str: ... 48 49def getproxies() -> Dict[str, str]: ... 50def parse_http_list(s: str) -> List[str]: ... 51def parse_keqv_list(l: List[str]) -> Dict[str, str]: ... 52 53if sys.platform == "win32" or sys.platform == "darwin": 54 def proxy_bypass(host: str) -> Any: ... # Undocumented 55 56else: 57 def proxy_bypass(host: str, proxies: Optional[Mapping[str, str]] = ...) -> Any: ... # Undocumented 58 59class Request: 60 @property 61 def full_url(self) -> str: ... 62 @full_url.setter 63 def full_url(self, value: str) -> None: ... 64 @full_url.deleter 65 def full_url(self) -> None: ... 66 type: str 67 host: str 68 origin_req_host: str 69 selector: str 70 data: Optional[bytes] 71 headers: Dict[str, str] 72 unredirected_hdrs: Dict[str, str] 73 unverifiable: bool 74 method: Optional[str] 75 timeout: Optional[float] # Undocumented, only set after __init__() by OpenerDirector.open() 76 def __init__( 77 self, 78 url: str, 79 data: Optional[bytes] = ..., 80 headers: Dict[str, str] = ..., 81 origin_req_host: Optional[str] = ..., 82 unverifiable: bool = ..., 83 method: Optional[str] = ..., 84 ) -> None: ... 85 def get_method(self) -> str: ... 86 def add_header(self, key: str, val: str) -> None: ... 87 def add_unredirected_header(self, key: str, val: str) -> None: ... 88 def has_header(self, header_name: str) -> bool: ... 89 def remove_header(self, header_name: str) -> None: ... 90 def get_full_url(self) -> str: ... 91 def set_proxy(self, host: str, type: str) -> None: ... 92 @overload 93 def get_header(self, header_name: str) -> Optional[str]: ... 94 @overload 95 def get_header(self, header_name: str, default: _T) -> Union[str, _T]: ... 96 def header_items(self) -> List[Tuple[str, str]]: ... 97 def has_proxy(self) -> bool: ... 98 99class OpenerDirector: 100 addheaders: List[Tuple[str, str]] 101 def add_handler(self, handler: BaseHandler) -> None: ... 102 def open(self, fullurl: Union[str, Request], data: Optional[bytes] = ..., timeout: Optional[float] = ...) -> _UrlopenRet: ... 103 def error(self, proto: str, *args: Any) -> _UrlopenRet: ... 104 def close(self) -> None: ... 105 106class BaseHandler: 107 handler_order: ClassVar[int] 108 parent: OpenerDirector 109 def add_parent(self, parent: OpenerDirector) -> None: ... 110 def close(self) -> None: ... 111 112class HTTPDefaultErrorHandler(BaseHandler): 113 def http_error_default( 114 self, req: Request, fp: IO[bytes], code: int, msg: str, hdrs: Mapping[str, str] 115 ) -> HTTPError: ... # undocumented 116 117class HTTPRedirectHandler(BaseHandler): 118 max_redirections: ClassVar[int] # undocumented 119 max_repeats: ClassVar[int] # undocumented 120 inf_msg: ClassVar[str] # undocumented 121 def redirect_request( 122 self, req: Request, fp: IO[bytes], code: int, msg: str, headers: Mapping[str, str], newurl: str 123 ) -> Optional[Request]: ... 124 def http_error_301( 125 self, req: Request, fp: IO[bytes], code: int, msg: str, headers: Mapping[str, str] 126 ) -> Optional[_UrlopenRet]: ... 127 def http_error_302( 128 self, req: Request, fp: IO[bytes], code: int, msg: str, headers: Mapping[str, str] 129 ) -> Optional[_UrlopenRet]: ... 130 def http_error_303( 131 self, req: Request, fp: IO[bytes], code: int, msg: str, headers: Mapping[str, str] 132 ) -> Optional[_UrlopenRet]: ... 133 def http_error_307( 134 self, req: Request, fp: IO[bytes], code: int, msg: str, headers: Mapping[str, str] 135 ) -> Optional[_UrlopenRet]: ... 136 137class HTTPCookieProcessor(BaseHandler): 138 cookiejar: CookieJar 139 def __init__(self, cookiejar: Optional[CookieJar] = ...) -> None: ... 140 def http_request(self, request: Request) -> Request: ... # undocumented 141 def http_response(self, request: Request, response: HTTPResponse) -> HTTPResponse: ... # undocumented 142 def https_request(self, request: Request) -> Request: ... # undocumented 143 def https_response(self, request: Request, response: HTTPResponse) -> HTTPResponse: ... # undocumented 144 145class ProxyHandler(BaseHandler): 146 def __init__(self, proxies: Optional[Dict[str, str]] = ...) -> None: ... 147 def proxy_open(self, req: Request, proxy: str, type: str) -> Optional[_UrlopenRet]: ... # undocumented 148 # TODO add a method for every (common) proxy protocol 149 150class HTTPPasswordMgr: 151 def add_password(self, realm: str, uri: Union[str, Sequence[str]], user: str, passwd: str) -> None: ... 152 def find_user_password(self, realm: str, authuri: str) -> Tuple[Optional[str], Optional[str]]: ... 153 def is_suburi(self, base: str, test: str) -> bool: ... # undocumented 154 def reduce_uri(self, uri: str, default_port: bool = ...) -> str: ... # undocumented 155 156class HTTPPasswordMgrWithDefaultRealm(HTTPPasswordMgr): 157 def add_password(self, realm: Optional[str], uri: Union[str, Sequence[str]], user: str, passwd: str) -> None: ... 158 def find_user_password(self, realm: Optional[str], authuri: str) -> Tuple[Optional[str], Optional[str]]: ... 159 160class HTTPPasswordMgrWithPriorAuth(HTTPPasswordMgrWithDefaultRealm): 161 def add_password( 162 self, realm: Optional[str], uri: Union[str, Sequence[str]], user: str, passwd: str, is_authenticated: bool = ... 163 ) -> None: ... 164 def update_authenticated(self, uri: Union[str, Sequence[str]], is_authenticated: bool = ...) -> None: ... 165 def is_authenticated(self, authuri: str) -> bool: ... 166 167class AbstractBasicAuthHandler: 168 rx: ClassVar[Pattern[str]] # undocumented 169 passwd: HTTPPasswordMgr 170 add_password: Callable[[str, Union[str, Sequence[str]], str, str], None] 171 def __init__(self, password_mgr: Optional[HTTPPasswordMgr] = ...) -> None: ... 172 def http_error_auth_reqed(self, authreq: str, host: str, req: Request, headers: Mapping[str, str]) -> None: ... 173 def http_request(self, req: Request) -> Request: ... # undocumented 174 def http_response(self, req: Request, response: HTTPResponse) -> HTTPResponse: ... # undocumented 175 def https_request(self, req: Request) -> Request: ... # undocumented 176 def https_response(self, req: Request, response: HTTPResponse) -> HTTPResponse: ... # undocumented 177 def retry_http_basic_auth(self, host: str, req: Request, realm: str) -> Optional[_UrlopenRet]: ... # undocumented 178 179class HTTPBasicAuthHandler(AbstractBasicAuthHandler, BaseHandler): 180 auth_header: ClassVar[str] # undocumented 181 def http_error_401( 182 self, req: Request, fp: IO[bytes], code: int, msg: str, headers: Mapping[str, str] 183 ) -> Optional[_UrlopenRet]: ... 184 185class ProxyBasicAuthHandler(AbstractBasicAuthHandler, BaseHandler): 186 auth_header: ClassVar[str] 187 def http_error_407( 188 self, req: Request, fp: IO[bytes], code: int, msg: str, headers: Mapping[str, str] 189 ) -> Optional[_UrlopenRet]: ... 190 191class AbstractDigestAuthHandler: 192 def __init__(self, passwd: Optional[HTTPPasswordMgr] = ...) -> None: ... 193 def reset_retry_count(self) -> None: ... 194 def http_error_auth_reqed(self, auth_header: str, host: str, req: Request, headers: Mapping[str, str]) -> None: ... 195 def retry_http_digest_auth(self, req: Request, auth: str) -> Optional[_UrlopenRet]: ... 196 def get_cnonce(self, nonce: str) -> str: ... 197 def get_authorization(self, req: Request, chal: Mapping[str, str]) -> str: ... 198 def get_algorithm_impls(self, algorithm: str) -> Tuple[Callable[[str], str], Callable[[str, str], str]]: ... 199 def get_entity_digest(self, data: Optional[bytes], chal: Mapping[str, str]) -> Optional[str]: ... 200 201class HTTPDigestAuthHandler(BaseHandler, AbstractDigestAuthHandler): 202 auth_header: ClassVar[str] # undocumented 203 def http_error_401( 204 self, req: Request, fp: IO[bytes], code: int, msg: str, headers: Mapping[str, str] 205 ) -> Optional[_UrlopenRet]: ... 206 207class ProxyDigestAuthHandler(BaseHandler, AbstractDigestAuthHandler): 208 auth_header: ClassVar[str] # undocumented 209 def http_error_407( 210 self, req: Request, fp: IO[bytes], code: int, msg: str, headers: Mapping[str, str] 211 ) -> Optional[_UrlopenRet]: ... 212 213class AbstractHTTPHandler(BaseHandler): # undocumented 214 def __init__(self, debuglevel: int = ...) -> None: ... 215 def set_http_debuglevel(self, level: int) -> None: ... 216 def do_request_(self, request: Request) -> Request: ... 217 def do_open(self, http_class: _HTTPConnectionProtocol, req: Request, **http_conn_args: Any) -> HTTPResponse: ... 218 219class HTTPHandler(AbstractHTTPHandler): 220 def http_open(self, req: Request) -> HTTPResponse: ... 221 def http_request(self, request: Request) -> Request: ... # undocumented 222 223class HTTPSHandler(AbstractHTTPHandler): 224 def __init__( 225 self, debuglevel: int = ..., context: Optional[ssl.SSLContext] = ..., check_hostname: Optional[bool] = ... 226 ) -> None: ... 227 def https_open(self, req: Request) -> HTTPResponse: ... 228 def https_request(self, request: Request) -> Request: ... # undocumented 229 230class FileHandler(BaseHandler): 231 names: ClassVar[Optional[Tuple[str, ...]]] # undocumented 232 def file_open(self, req: Request) -> addinfourl: ... 233 def get_names(self) -> Tuple[str, ...]: ... # undocumented 234 def open_local_file(self, req: Request) -> addinfourl: ... # undocumented 235 236class DataHandler(BaseHandler): 237 def data_open(self, req: Request) -> addinfourl: ... 238 239class ftpwrapper: # undocumented 240 def __init__( 241 self, user: str, passwd: str, host: str, port: int, dirs: str, timeout: Optional[float] = ..., persistent: bool = ... 242 ) -> None: ... 243 def close(self) -> None: ... 244 def endtransfer(self) -> None: ... 245 def file_close(self) -> None: ... 246 def init(self) -> None: ... 247 def real_close(self) -> None: ... 248 def retrfile(self, file: str, type: str) -> Tuple[addclosehook, int]: ... 249 250class FTPHandler(BaseHandler): 251 def ftp_open(self, req: Request) -> addinfourl: ... 252 def connect_ftp( 253 self, user: str, passwd: str, host: str, port: int, dirs: str, timeout: float 254 ) -> ftpwrapper: ... # undocumented 255 256class CacheFTPHandler(FTPHandler): 257 def setTimeout(self, t: float) -> None: ... 258 def setMaxConns(self, m: int) -> None: ... 259 def check_cache(self) -> None: ... # undocumented 260 def clear_cache(self) -> None: ... # undocumented 261 def connect_ftp( 262 self, user: str, passwd: str, host: str, port: int, dirs: str, timeout: float 263 ) -> ftpwrapper: ... # undocumented 264 265class UnknownHandler(BaseHandler): 266 def unknown_open(self, req: Request) -> NoReturn: ... 267 268class HTTPErrorProcessor(BaseHandler): 269 def http_response(self, request: Request, response: HTTPResponse) -> _UrlopenRet: ... 270 def https_response(self, request: Request, response: HTTPResponse) -> _UrlopenRet: ... 271 272def urlretrieve( 273 url: str, 274 filename: Optional[StrOrBytesPath] = ..., 275 reporthook: Optional[Callable[[int, int, int], None]] = ..., 276 data: Optional[bytes] = ..., 277) -> Tuple[str, HTTPMessage]: ... 278def urlcleanup() -> None: ... 279 280class URLopener: 281 version: ClassVar[str] 282 def __init__(self, proxies: Optional[Dict[str, str]] = ..., **x509: str) -> None: ... 283 def open(self, fullurl: str, data: Optional[bytes] = ...) -> _UrlopenRet: ... 284 def open_unknown(self, fullurl: str, data: Optional[bytes] = ...) -> _UrlopenRet: ... 285 def retrieve( 286 self, 287 url: str, 288 filename: Optional[str] = ..., 289 reporthook: Optional[Callable[[int, int, int], None]] = ..., 290 data: Optional[bytes] = ..., 291 ) -> Tuple[str, Optional[Message]]: ... 292 def addheader(self, *args: Tuple[str, str]) -> None: ... # undocumented 293 def cleanup(self) -> None: ... # undocumented 294 def close(self) -> None: ... # undocumented 295 def http_error( 296 self, url: str, fp: IO[bytes], errcode: int, errmsg: str, headers: Mapping[str, str], data: Optional[bytes] = ... 297 ) -> _UrlopenRet: ... # undocumented 298 def http_error_default( 299 self, url: str, fp: IO[bytes], errcode: int, errmsg: str, headers: Mapping[str, str] 300 ) -> _UrlopenRet: ... # undocumented 301 def open_data(self, url: str, data: Optional[bytes] = ...) -> addinfourl: ... # undocumented 302 def open_file(self, url: str) -> addinfourl: ... # undocumented 303 def open_ftp(self, url: str) -> addinfourl: ... # undocumented 304 def open_http(self, url: str, data: Optional[bytes] = ...) -> _UrlopenRet: ... # undocumented 305 def open_https(self, url: str, data: Optional[bytes] = ...) -> _UrlopenRet: ... # undocumented 306 def open_local_file(self, url: str) -> addinfourl: ... # undocumented 307 def open_unknown_proxy(self, proxy: str, fullurl: str, data: Optional[bytes] = ...) -> None: ... # undocumented 308 309class FancyURLopener(URLopener): 310 def prompt_user_passwd(self, host: str, realm: str) -> Tuple[str, str]: ... 311 def get_user_passwd(self, host: str, realm: str, clear_cache: int = ...) -> Tuple[str, str]: ... # undocumented 312 def http_error_301( 313 self, url: str, fp: IO[bytes], errcode: int, errmsg: str, headers: Mapping[str, str], data: Optional[bytes] = ... 314 ) -> Optional[Union[_UrlopenRet, addinfourl]]: ... # undocumented 315 def http_error_302( 316 self, url: str, fp: IO[bytes], errcode: int, errmsg: str, headers: Mapping[str, str], data: Optional[bytes] = ... 317 ) -> Optional[Union[_UrlopenRet, addinfourl]]: ... # undocumented 318 def http_error_303( 319 self, url: str, fp: IO[bytes], errcode: int, errmsg: str, headers: Mapping[str, str], data: Optional[bytes] = ... 320 ) -> Optional[Union[_UrlopenRet, addinfourl]]: ... # undocumented 321 def http_error_307( 322 self, url: str, fp: IO[bytes], errcode: int, errmsg: str, headers: Mapping[str, str], data: Optional[bytes] = ... 323 ) -> Optional[Union[_UrlopenRet, addinfourl]]: ... # undocumented 324 def http_error_401( 325 self, 326 url: str, 327 fp: IO[bytes], 328 errcode: int, 329 errmsg: str, 330 headers: Mapping[str, str], 331 data: Optional[bytes] = ..., 332 retry: bool = ..., 333 ) -> Optional[_UrlopenRet]: ... # undocumented 334 def http_error_407( 335 self, 336 url: str, 337 fp: IO[bytes], 338 errcode: int, 339 errmsg: str, 340 headers: Mapping[str, str], 341 data: Optional[bytes] = ..., 342 retry: bool = ..., 343 ) -> Optional[_UrlopenRet]: ... # undocumented 344 def http_error_default( 345 self, url: str, fp: IO[bytes], errcode: int, errmsg: str, headers: Mapping[str, str] 346 ) -> addinfourl: ... # undocumented 347 def redirect_internal( 348 self, url: str, fp: IO[bytes], errcode: int, errmsg: str, headers: Mapping[str, str], data: Optional[bytes] 349 ) -> Optional[_UrlopenRet]: ... # undocumented 350 def retry_http_basic_auth( 351 self, url: str, realm: str, data: Optional[bytes] = ... 352 ) -> Optional[_UrlopenRet]: ... # undocumented 353 def retry_https_basic_auth( 354 self, url: str, realm: str, data: Optional[bytes] = ... 355 ) -> Optional[_UrlopenRet]: ... # undocumented 356 def retry_proxy_http_basic_auth( 357 self, url: str, realm: str, data: Optional[bytes] = ... 358 ) -> Optional[_UrlopenRet]: ... # undocumented 359 def retry_proxy_https_basic_auth( 360 self, url: str, realm: str, data: Optional[bytes] = ... 361 ) -> Optional[_UrlopenRet]: ... # undocumented 362