From 25d0036a57ee9823221a48e58367e92c4378caac Mon Sep 17 00:00:00 2001
From: Sebastian Rittau <srittau@rittau.biz>
Date: Tue, 28 Jan 2020 11:02:48 +0100
Subject: [PATCH] Improve imaplib return types

Mark CommandResults as obsolete.

Also fix types of tagged_commands and untagged_responses.

Based on a discussion in #3655.
---
 stdlib/2and3/imaplib.pyi | 28 +++++++++++++++++-----------
 1 file changed, 17 insertions(+), 11 deletions(-)

diff --git a/stdlib/2and3/imaplib.pyi b/stdlib/2and3/imaplib.pyi
index 07f770dfb3ce..2d54d5cd3a6e 100644
--- a/stdlib/2and3/imaplib.pyi
+++ b/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
 
+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[str, Optional[bytes]]
+    untagged_responses: Dict[str, List[Union[bytes, Tuple[bytes, bytes]]]]
     continuation_response: str = ...
     is_readonly: bool = ...
     tagnum: int = ...
@@ -57,30 +63,30 @@ class IMAP4:
         def __enter__(self) -> IMAP4: ...
         def __exit__(self, *args) -> None: ...
     def expunge(self) -> CommandResults: ...
-    def fetch(self, message_set: str, message_parts: str) -> 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 = ...) -> CommandResults: ...
-    def login(self, user: str, password: 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) -> 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) -> 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 = ...) -> 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 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: ...