filled in stub files

Added flags to messages, moved classes out of __init__.py, and documented that the inbox is where Imbox.messages are from without any folder argument.

README.rst

@@ -52,6 +52,12 @@ Usage
         # Un-flagged messages
         inbox_unflagged_messages = imbox.messages(unflagged=True)
 
+        # Flagged messages
+        flagged_messages = imbox.messages(flagged=True)
+
+        # Un-flagged messages
+        unflagged_messages = imbox.messages(unflagged=True)
+
         # Messages sent FROM
         inbox_messages_from = imbox.messages(sent_from='sender@example.org')
 
@@ -73,6 +79,8 @@ Usage
         # Messages whose subjects contain a string
         inbox_messages_subject_christmas = imbox.messages(subject='Christmas')
 
+        # Messages from a specific folder
+        messages_in_folder_social = imbox.messages(folder='Social')
 
         for uid, message in all_inbox_messages:
         # Every message is an object with the following keys

imbox/imap.pyi

@@ -0,0 +1,13 @@
+from imaplib import IMAP4, IMAP4_SSL
+from ssl import SSLContext
+from typing import Optional, Union, Tuple, List
+
+
+class ImapTransport:
+
+    def __init__(self, hostname: str, port: Optional[int], ssl: bool,
+                 ssl_context: Optional[SSLContext], starttls: bool) -> None: ...
+
+    def list_folders(self) -> Tuple[str, List[bytes]]: ...
+
+    def connect(self, username: str, password: str) -> Union[IMAP4, IMAP4_SSL]: ...

imbox/imbox.pyi

@@ -0,0 +1,31 @@
+import datetime
+from email._policybase import Policy
+from inspect import Traceback
+from ssl import SSLContext
+from typing import Optional, Union, Tuple, List
+
+
+class Imbox:
+
+    def __init__(self, hostname: str, username: Optional[str], password: Optional[str], ssl: bool,
+                 port: Optional[int], ssl_context: Optional[SSLContext], policy: Optional[Policy], starttls: bool): ...
+
+    def __enter__(self) -> 'Imbox': ...
+
+    def __exit__(self, type: Exception, value: str, traceback: Traceback) -> None: ...
+
+    def logout(self) -> None: ...
+
+    def mark_seen(self, uid: bytes) -> None: ...
+
+    def mark_flag(self, uid: bytes) -> None: ...
+
+    def delete(self, uid: bytes) -> None: ...
+
+    def copy(self, uid: bytes, destination_folder: Union[bytes, str]) -> Tuple[str, Union[list, List[None, bytes]]]: ...
+
+    def move(self, uid: bytes, destination_folder: Union[bytes, str]) -> None: ...
+
+    def messages(self, **kwargs: Union[bool, str, datetime.date]) -> 'Messages': ...
+
+    def folders(self) -> Tuple[str, List[bytes]]: ...

imbox/messages.pyi

@@ -0,0 +1,28 @@
+import datetime
+from email._policybase import Policy
+from imaplib import IMAP4, IMAP4_SSL
+from typing import Union, List, Generator, Tuple
+
+
+class Messages:
+
+    def __init__(self,
+                 connection: Union[IMAP4, IMAP4_SSL],
+                 parser_policy: Policy,
+                 **kwargs: Union[bool, str, datetime.date]) -> None: ...
+
+    def _fetch_email(self, uid: bytes) -> 'Struct': ...
+
+    def _query_uids(self, **kwargs: Union[bool, str, datetime.date]) -> List[bytes]: ...
+
+    def _fetch_email_list(self) -> Generator[Tuple[bytes, 'Struct']]: ...
+
+    def __repr__(self) -> str: ...
+
+    def __iter__(self) -> Generator[Tuple[bytes, 'Struct']]: ...
+
+    def __next__(self) -> 'Messages': ...
+
+    def __len__(self) -> int: ...
+
+    def __getitem__(self, index) -> Union['Struct', List['Struct']]: ...

imbox/parser.pyi

@@ -0,0 +1,30 @@
+import datetime
+from email._policybase import Policy
+from email.message import Message
+from imaplib import IMAP4_SSL
+import io
+from typing import Union, Dict, List, KeysView, Tuple, Optional
+
+
+class Struct:
+    def __init__(self, **entries: Union[
+        str, datetime.datetime, Dict[str, str], list, List[Dict[str, str]]
+    ]) -> None: ...
+
+    def keys(self) -> KeysView: ...
+
+    def __repr__(self) -> str: ...
+
+def decode_mail_header(value: str, default_charset: str) -> str: ...
+
+def get_mail_addresses(message: Message, header_name: str) -> List[Dict[str, str]]: ...
+
+def decode_param(param: str) -> Tuple[str, str]: ...
+
+def parse_attachment(message_part: Message) -> Optional[Dict[str, Union[int, str, io.BytesIO]]]: ...
+
+def decode_content(message: Message) -> str: ...
+
+def fetch_email_by_uid(uid: bytes, connection: IMAP4_SSL, parser_policy: Optional[Policy]) -> Struct: ...
+
+def parse_email(raw_email: bytes, policy: Optional[Policy]) -> Struct: ...

imbox/query.pyi

@@ -0,0 +1,7 @@
+import datetime
+from typing import Union
+
+
+def format_date(date: Union[str, datetime.date]) -> str: ...
+
+def build_search_query(**kwargs: Union[bool, str, datetime.date]) -> str: ...

imbox/utils.pyi

@@ -0,0 +1,6 @@
+from typing import Optional, Union
+
+
+def str_encode(value: Union[str, bytes], encoding: Optional[str], errors: str) -> str: ...
+
+def str_decode(value: Union[str, bytes], encoding: Optional[str], errors: str) -> Union[str, bytes]: ...