Add stubs for HTTP Handler classes in py2/urllib2 & py3/urllib.request (#2710)

* HTTP Handler class annotations for py2/urllib2 & py3/urllib.request

Add full annotations for the following classes:

* Python 2:

    * `urllib2.AbstractHTTPHandler`
    * `urllib2.HTTPHandler`
    * `urllib2.HTTPsHandler`

* Python 3:

    * `urllib.request.AbstractHTTPHandler`
    * `urllib.request.HTTPHandler`
    * `urllib.request.HTTPsHandler`

This information is largely undocumented, and was obtained by directly examining
the Python source code:

* Python 2 (v2.7.15) - https://github.com/python/cpython/blob/v2.7.15/Lib/urllib2.py#L1115-L1243
* Python 3 (v3.7.1) - https://github.com/python/cpython/blob/v3.7.1/Lib/urllib/request.py#L1224-L1364

`urllib2.AbstractHTTPHandler.do_open` takes as a parameter either
`HTTPConnection` or `HTTPSConnection`--one of the classes, not an instance of
either--and constructs an object using only a few of the parameters that either
constructor could use. `HTTPConnectionProtocol` in `stdlib/2/httplib.pyi`
follows a similar patten to `HTTPConnectionProtocol` added to
`stdlib/3/http/client.pyi` in pull request #2582 to describe the type of the
`http_class` that is passed to `do_open`.

stdlib/2/httplib.pyi

@@ -3,8 +3,9 @@
 # Generated by stubgen and manually massaged a bit.
 # Needs lots more work!
 
-from typing import Any, Dict, Optional
+from typing import Any, Dict, Optional, Protocol
 import mimetools
+import ssl
 
 class HTTPMessage(mimetools.Message):
     def addcontinue(self, key: str, more: str) -> None: ...
@@ -38,6 +39,15 @@ class HTTPResponse:
     def getheader(self, name, default: Optional[Any] = ...): ...
     def getheaders(self): ...
 
+# This is an API stub only for HTTPConnection and HTTPSConnection, as used in
+# urllib2.AbstractHTTPHandler.do_open, which takes either the class
+# HTTPConnection or the class HTTPSConnection, *not* an instance of either
+# class. do_open does not use all of the parameters of HTTPConnection.__init__
+# or HTTPSConnection.__init__, so HTTPConnectionProtocol only implements the
+# parameters that do_open does use.
+class HTTPConnectionProtocol(Protocol):
+    def __call__(self, host: str, timeout: int = ..., **http_con_args: Any) -> HTTPConnection: ...
+
 class HTTPConnection:
     response_class = ...  # type: Any
     default_port = ...  # type: Any

stdlib/2/urllib2.pyi

@@ -2,7 +2,7 @@
 import ssl
 from typing import Any, AnyStr, Dict, List, Union, Optional, Mapping, Callable, Sequence, Tuple, Type
 from urllib import addinfourl
-from httplib import HTTPResponse
+from httplib import HTTPConnectionProtocol, HTTPResponse
 
 _string = Union[str, unicode]
 
@@ -128,19 +128,23 @@ class ProxyDigestAuthHandler(BaseHandler, AbstractDigestAuthHandler):
     handler_order = ...  # type: int
     def http_error_407(self, req, fp, code, msg, headers): ...
 
-class AbstractHTTPHandler(BaseHandler):
+class AbstractHTTPHandler(BaseHandler):  # undocumented
     def __init__(self, debuglevel: int = ...) -> None: ...
-    def do_request_(self, request): ...
-    def do_open(self, http_class, req): ...  # undocumented
+    def set_http_debuglevel(self, level: int) -> None: ...
+    def do_request_(self, request: Request) -> Request: ...
+    def do_open(self,
+                http_class: HTTPConnectionProtocol,
+                req: Request,
+                **http_conn_args: Optional[Any]) -> addinfourl: ...
 
 class HTTPHandler(AbstractHTTPHandler):
-    def http_open(self, req): ...
-    def http_request(self, request): ...
+    def http_open(self, req: Request) -> addinfourl: ...
+    def http_request(self, request: Request) -> Request: ...  # undocumented
 
 class HTTPSHandler(AbstractHTTPHandler):
-    def __init__(self, debuglevel: int = ..., context: Optional[Any] = ...): ...
-    def https_open(self, req): ...
-    def https_request(self, request): ...
+    def __init__(self, debuglevel: int = ..., context: Optional[ssl.SSLContext] = ...) -> None: ...
+    def https_open(self, req: Request) -> addinfourl: ...
+    def https_request(self, request: Request) -> Request: ...  # undocumented
 
 class HTTPCookieProcessor(BaseHandler):
     def __init__(self, cookiejar: Optional[Any] = ...): ...

stdlib/3/urllib/request.pyi

@@ -157,17 +157,25 @@ class ProxyDigestAuthHandler(BaseHandler, AbstractDigestAuthHandler):
     def http_error_407(self, req: Request, fp: IO[str], code: int, msg: int,
                        hdrs: Mapping[str, str]) -> Optional[_UrlopenRet]: ...
 
-class HTTPHandler(BaseHandler):
-    def http_open(self, req: Request) -> HTTPResponse: ...
-    def do_open(self,  # undocumented
+class AbstractHTTPHandler(BaseHandler):  # undocumented
+    def __init__(self, debuglevel: int = ...) -> None: ...
+    def set_http_debuglevel(self, level: int) -> None: ...
+    def do_request_(self, request: Request) -> Request: ...
+    def do_open(self,
                 http_class: HTTPConnectionProtocol,
-                req: Request) -> HTTPResponse: ...
+                req: Request,
+                **http_conn_args: Any) -> HTTPResponse: ...
 
-class HTTPSHandler(BaseHandler):
+class HTTPHandler(AbstractHTTPHandler):
+    def http_open(self, req: Request) -> HTTPResponse: ...
+    def http_request(self, request: Request) -> Request: ...  # undocumented
+
+class HTTPSHandler(AbstractHTTPHandler):
     def __init__(self, debuglevel: int = ...,
                  context: Optional[ssl.SSLContext] = ...,
-                 check_hostname: bool = ...) -> None: ...
+                 check_hostname: Optional[bool] = ...) -> None: ...
     def https_open(self, req: Request) -> HTTPResponse: ...
+    def https_request(self, request: Request) -> Request: ...  # undocumented
 
 class FileHandler(BaseHandler):
     def file_open(self, req: Request) -> addinfourl: ...