Improve imaplib return types (#3670)

* Improve imaplib return types

Mark CommandResults as obsolete.

Also fix types of tagged_commands and untagged_responses.

Based on a discussion in #3655.

* Fix type of tagged_commands

* Fix IMAP4.tagged_commands type

* Mark CommandResults as private

* Fix

Author: srittau

stdlib/2and3/imaplib.pyi

@@ -1,5 +1,3 @@
-# Stubs for imaplib (Python 2)
-
 import imaplib
 import subprocess
 import sys
@@ -8,8 +6,16 @@ from socket import socket as _socket
 from ssl import SSLSocket, SSLContext
 from typing import Any, Callable, Dict, IO, List, Optional, Pattern, Text, Tuple, Type, Union
 
-CommandResults = Tuple[str, List[Any]]
+if sys.version_info >= (3, 8):
+    from typing import Literal
+else:
+    from typing_extensions import Literal
+
+# TODO: Commands should use their actual return types, not this type alias.
+#       E.g. Tuple[Literal["OK"], List[bytes]]
+_CommandResults = Tuple[str, List[Any]]
 
+_AnyResponseData = Union[List[None], List[Union[bytes, Tuple[bytes, bytes]]]]
 
 class IMAP4:
     error: Type[Exception] = ...
@@ -19,8 +25,8 @@ class IMAP4:
     debug: int = ...
     state: str = ...
     literal: Optional[Text] = ...
-    tagged_commands: Dict[str, str] = ...
-    untagged_responses: Dict[str, str] = ...
+    tagged_commands: Dict[bytes, Optional[List[bytes]]]
+    untagged_responses: Dict[str, List[Union[bytes, Tuple[bytes, bytes]]]]
     continuation_response: str = ...
     is_readonly: bool = ...
     tagnum: int = ...
@@ -41,53 +47,53 @@ class IMAP4:
     def send(self, data: bytes) -> None: ...
     def shutdown(self) -> None: ...
     def socket(self) -> _socket: ...
-    def recent(self) -> CommandResults: ...
-    def response(self, code: str) -> CommandResults: ...
+    def recent(self) -> _CommandResults: ...
+    def response(self, code: str) -> _CommandResults: ...
     def append(self, mailbox: str, flags: str, date_time: str, message: str) -> str: ...
     def authenticate(self, mechanism: str, authobject: Callable[[bytes], Optional[bytes]]) -> Tuple[str, str]: ...
-    def capability(self) -> CommandResults: ...
-    def check(self) -> CommandResults: ...
-    def close(self) -> CommandResults: ...
-    def copy(self, message_set: str, new_mailbox: str) -> CommandResults: ...
-    def create(self, mailbox: str) -> CommandResults: ...
-    def delete(self, mailbox: str) -> CommandResults: ...
-    def deleteacl(self, mailbox: str, who: str) -> CommandResults: ...
+    def capability(self) -> _CommandResults: ...
+    def check(self) -> _CommandResults: ...
+    def close(self) -> _CommandResults: ...
+    def copy(self, message_set: str, new_mailbox: str) -> _CommandResults: ...
+    def create(self, mailbox: str) -> _CommandResults: ...
+    def delete(self, mailbox: str) -> _CommandResults: ...
+    def deleteacl(self, mailbox: str, who: str) -> _CommandResults: ...
     if sys.version_info >= (3, 5):
-        def enable(self, capability: str) -> CommandResults: ...
+        def enable(self, capability: str) -> _CommandResults: ...
         def __enter__(self) -> IMAP4: ...
         def __exit__(self, *args) -> None: ...
-    def expunge(self) -> CommandResults: ...
-    def fetch(self, message_set: str, message_parts: str) -> CommandResults: ...
-    def getacl(self, mailbox: str) -> CommandResults: ...
-    def getannotation(self, mailbox: str, entry: str, attribute: str) -> CommandResults: ...
-    def getquota(self, root: str) -> CommandResults: ...
-    def getquotaroot(self, mailbox: str) -> CommandResults: ...
-    def list(self, directory: str = ..., pattern: str = ...) -> CommandResults: ...
-    def login(self, user: str, password: str) -> CommandResults: ...
-    def login_cram_md5(self, user: str, password: str) -> CommandResults: ...
-    def logout(self) -> CommandResults: ...
-    def lsub(self, directory: str = ..., pattern: str = ...) -> CommandResults: ...
-    def myrights(self, mailbox: str) -> CommandResults: ...
-    def namespace(self) -> CommandResults: ...
-    def noop(self) -> CommandResults: ...
-    def partial(self, message_num: str, message_part: str, start: str, length: str) -> CommandResults: ...
-    def proxyauth(self, user: str) -> CommandResults: ...
-    def rename(self, oldmailbox: str, newmailbox: str) -> CommandResults: ...
-    def search(self, charset: Optional[str], *criteria: str) -> CommandResults: ...
-    def select(self, mailbox: str = ..., readonly: bool = ...) -> CommandResults: ...
-    def setacl(self, mailbox: str, who: str, what: str) -> CommandResults: ...
-    def setannotation(self, *args: str) -> CommandResults: ...
-    def setquota(self, root: str, limits: str) -> CommandResults: ...
-    def sort(self, sort_criteria: str, charset: str, *search_criteria: str) -> CommandResults: ...
+    def expunge(self) -> _CommandResults: ...
+    def fetch(self, message_set: str, message_parts: str) -> Tuple[str, _AnyResponseData]: ...
+    def getacl(self, mailbox: str) -> _CommandResults: ...
+    def getannotation(self, mailbox: str, entry: str, attribute: str) -> _CommandResults: ...
+    def getquota(self, root: str) -> _CommandResults: ...
+    def getquotaroot(self, mailbox: str) -> _CommandResults: ...
+    def list(self, directory: str = ..., pattern: str = ...) -> Tuple[str, _AnyResponseData]: ...
+    def login(self, user: str, password: str) -> Tuple[Literal["OK"], List[bytes]]: ...
+    def login_cram_md5(self, user: str, password: str) -> _CommandResults: ...
+    def logout(self) -> Tuple[str, _AnyResponseData]: ...
+    def lsub(self, directory: str = ..., pattern: str = ...) -> _CommandResults: ...
+    def myrights(self, mailbox: str) -> _CommandResults: ...
+    def namespace(self) -> _CommandResults: ...
+    def noop(self) -> Tuple[str, List[bytes]]: ...
+    def partial(self, message_num: str, message_part: str, start: str, length: str) -> _CommandResults: ...
+    def proxyauth(self, user: str) -> _CommandResults: ...
+    def rename(self, oldmailbox: str, newmailbox: str) -> _CommandResults: ...
+    def search(self, charset: Optional[str], *criteria: str) -> _CommandResults: ...
+    def select(self, mailbox: str = ..., readonly: bool = ...) -> Tuple[str, List[Optional[bytes]]]: ...
+    def setacl(self, mailbox: str, who: str, what: str) -> _CommandResults: ...
+    def setannotation(self, *args: str) -> _CommandResults: ...
+    def setquota(self, root: str, limits: str) -> _CommandResults: ...
+    def sort(self, sort_criteria: str, charset: str, *search_criteria: str) -> _CommandResults: ...
     if sys.version_info >= (3,):
-        def starttls(self, ssl_context: Optional[Any] = ...) -> CommandResults: ...
-    def status(self, mailbox: str, names: str) -> CommandResults: ...
-    def store(self, message_set: str, command: str, flags: str) -> CommandResults: ...
-    def subscribe(self, mailbox: str) -> CommandResults: ...
-    def thread(self, threading_algorithm: str, charset: str, *search_criteria: str) -> CommandResults: ...
-    def uid(self, command: str, *args: str) -> CommandResults: ...
-    def unsubscribe(self, mailbox: str) -> CommandResults: ...
-    def xatom(self, name: str, *args: str) -> CommandResults: ...
+        def starttls(self, ssl_context: Optional[Any] = ...) -> Tuple[Literal["OK"], List[None]]: ...
+    def status(self, mailbox: str, names: str) -> _CommandResults: ...
+    def store(self, message_set: str, command: str, flags: str) -> _CommandResults: ...
+    def subscribe(self, mailbox: str) -> _CommandResults: ...
+    def thread(self, threading_algorithm: str, charset: str, *search_criteria: str) -> _CommandResults: ...
+    def uid(self, command: str, *args: str) -> _CommandResults: ...
+    def unsubscribe(self, mailbox: str) -> _CommandResults: ...
+    def xatom(self, name: str, *args: str) -> _CommandResults: ...
     def print_log(self) -> None: ...
 
 class IMAP4_SSL(IMAP4):