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