Skip to content

Commit

Permalink
Improve imaplib return types (#3670)
Browse files Browse the repository at this point in the history 
* 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
  • Loading branch information
@srittau
srittau authored Feb 22, 2020
1 parent 84c6e67 commit ca9505c
Showing 1 changed file with 52 additions and 46 deletions.
98 changes: 52 additions & 46 deletions stdlib/2and3/imaplib.pyi
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,3 @@
# Stubs for imaplib (Python 2)

import imaplib
import subprocess
import sys
Expand All @@ -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] = ...
Expand All @@ -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 = ...
Expand All @@ -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):
Expand Down

0 comments on commit ca9505c

Please sign in to comment.