From cd4572e43c0003fad80d3972e6faf4fe0443e602 Mon Sep 17 00:00:00 2001
From: "Gregory P. Smith" <greg@krypto.org>
Date: Mon, 12 Nov 2018 12:54:57 -0800
Subject: [PATCH] Annotate some missing http client and urllib APIs. (#2582)

---
 stdlib/2/httplib.pyi        |  2 ++
 stdlib/2/urllib2.pyi        |  2 +-
 stdlib/3/http/client.pyi    | 38 ++++++++++++++++++++++++++++++++-----
 stdlib/3/urllib/request.pyi |  5 ++++-
 4 files changed, 40 insertions(+), 7 deletions(-)

diff --git a/stdlib/2/httplib.pyi b/stdlib/2/httplib.pyi
index 57825635b..8aec02558 100644
--- a/stdlib/2/httplib.pyi
+++ b/stdlib/2/httplib.pyi
@@ -46,6 +46,8 @@ class HTTPConnection:
     timeout = ...  # type: Any
     source_address = ...  # type: Any
     sock = ...  # type: Any
+    host: str = ...
+    port: int = ...
     def __init__(self, host, port=None, strict=None, timeout=..., source_address=None) -> None: ...
     def set_tunnel(self, host, port=None, headers=None): ...
     def set_debuglevel(self, level): ...
diff --git a/stdlib/2/urllib2.pyi b/stdlib/2/urllib2.pyi
index f71a08b9c..136b269cd 100644
--- a/stdlib/2/urllib2.pyi
+++ b/stdlib/2/urllib2.pyi
@@ -131,7 +131,7 @@ class ProxyDigestAuthHandler(BaseHandler, AbstractDigestAuthHandler):
 class AbstractHTTPHandler(BaseHandler):
     def __init__(self, debuglevel: int = ...) -> None: ...
     def do_request_(self, request): ...
-    def do_open(self, http_class, req): ...
+    def do_open(self, http_class, req): ...  # undocumented
 
 class HTTPHandler(AbstractHTTPHandler):
     def http_open(self, req): ...
diff --git a/stdlib/3/http/client.pyi b/stdlib/3/http/client.pyi
index 486b57034..bd11f567e 100644
--- a/stdlib/3/http/client.pyi
+++ b/stdlib/3/http/client.pyi
@@ -1,5 +1,6 @@
 from typing import (
-    Any, Dict, IO, Iterable, List, Iterator, Mapping, Optional, Tuple, Type, TypeVar,
+    Any, Dict, IO, Iterable, List, Iterator, Mapping, Optional,
+    Protocol, Tuple, Type, TypeVar,
     Union,
     overload,
     BinaryIO,
@@ -107,6 +108,7 @@ if sys.version_info >= (3, 5):
         def info(self) -> email.message.Message: ...
         def geturl(self) -> str: ...
         def getcode(self) -> int: ...
+        def begin(self) -> None: ...
 else:
     class HTTPResponse(io.RawIOBase, BinaryIO):  # type: ignore
         msg = ...  # type: HTTPMessage
@@ -132,8 +134,24 @@ else:
         def info(self) -> email.message.Message: ...
         def geturl(self) -> str: ...
         def getcode(self) -> int: ...
+        def begin(self) -> None: ...
+
+# This is an API stub only for the class below, not a class itself.
+# urllib.request uses it for a parameter.
+class HTTPConnectionProtocol(Protocol):
+    if sys.version_info >= (3, 7):
+        def __call__(self, host: str, port: Optional[int] = ...,
+                     timeout: int = ...,
+                     source_address: Optional[Tuple[str, int]] = ...,
+                     blocksize: int = ...): ...
+    else:
+        def __call__(self, host: str, port: Optional[int] = ...,
+                     timeout: int = ...,
+                     source_address: Optional[Tuple[str, int]] = ...): ...
 
 class HTTPConnection:
+    host: str = ...
+    port: int = ...
     if sys.version_info >= (3, 7):
         def __init__(
             self,
@@ -148,9 +166,15 @@ class HTTPConnection:
             timeout: int = ...,
             source_address: Optional[Tuple[str, int]] = ...
         ) -> None: ...
-    def request(self, method: str, url: str,
-                body: Optional[_DataType] = ...,
-                headers: Mapping[str, str] = ...) -> None: ...
+    if sys.version_info >= (3, 6):
+        def request(self, method: str, url: str,
+                    body: Optional[_DataType] = ...,
+                    headers: Mapping[str, str] = ...,
+                    *, encode_chunked: bool = ...) -> None: ...
+    else:
+        def request(self, method: str, url: str,
+                    body: Optional[_DataType] = ...,
+                    headers: Mapping[str, str] = ...) -> None: ...
     def getresponse(self) -> HTTPResponse: ...
     def set_debuglevel(self, level: int) -> None: ...
     def set_tunnel(self, host: str, port: Optional[int] = ...,
@@ -160,7 +184,11 @@ class HTTPConnection:
     def putrequest(self, request: str, selector: str, skip_host: bool = ...,
                    skip_accept_encoding: bool = ...) -> None: ...
     def putheader(self, header: str, *argument: str) -> None: ...
-    def endheaders(self, message_body: Optional[_DataType] = ...) -> None: ...
+    if sys.version_info >= (3, 6):
+        def endheaders(self, message_body: Optional[_DataType] = ...,
+                       *, encode_chunked: bool = ...) -> None: ...
+    else:
+        def endheaders(self, message_body: Optional[_DataType] = ...) -> None: ...
     def send(self, data: _DataType) -> None: ...
 
 class HTTPSConnection(HTTPConnection):
diff --git a/stdlib/3/urllib/request.pyi b/stdlib/3/urllib/request.pyi
index 614e7b127..573b426ca 100644
--- a/stdlib/3/urllib/request.pyi
+++ b/stdlib/3/urllib/request.pyi
@@ -4,7 +4,7 @@ from typing import (
     Any, Callable, ClassVar, Dict, List, IO, Mapping, Optional, Sequence, Tuple,
     TypeVar, Union, overload, NoReturn,
 )
-from http.client import HTTPResponse, HTTPMessage
+from http.client import HTTPResponse, HTTPMessage, HTTPConnectionProtocol
 from http.cookiejar import CookieJar
 from email.message import Message
 from urllib.response import addinfourl
@@ -159,6 +159,9 @@ class ProxyDigestAuthHandler(BaseHandler, AbstractDigestAuthHandler):
 
 class HTTPHandler(BaseHandler):
     def http_open(self, req: Request) -> HTTPResponse: ...
+    def do_open(self,  # undocumented
+                http_class: HTTPConnectionProtocol,
+                req: Request) -> HTTPResponse: ...
 
 class HTTPSHandler(BaseHandler):
     def __init__(self, debuglevel: int = ...,