Add type stubs for email module and backend components

emails/__init__.pyi

@@ -0,0 +1,10 @@
+from typing import Any, Optional, Union, Tuple, List, Dict, Callable
+from .message import Message as Message, html as html
+from .utils import MessageID as MessageID
+
+__title__: str
+__version__: str
+__author__: str
+__license__: str
+__copyright__: str
+USER_AGENT: str

emails/backend/__init__.pyi

@@ -0,0 +1,2 @@
+from .factory import ObjectFactory as ObjectFactory
+from .smtp import SMTPBackend as SMTPBackend

emails/backend/factory.pyi

@@ -0,0 +1,12 @@
+from typing import Any, Dict, Type, TypeVar
+
+T = TypeVar('T')
+
+def simple_dict2str(d: Dict[str, Any]) -> str: ...
+
+class ObjectFactory:
+    cls: Type[Any]
+    pool: Dict[str, Any]
+    def __init__(self, cls: Type[Any]) -> None: ...
+    def __getitem__(self, k: Dict[str, Any]) -> Any: ...
+    def invalidate(self, k: Dict[str, Any]) -> Any: ...

emails/backend/response.pyi

@@ -0,0 +1,27 @@
+from typing import Any, Optional, List, Dict, Tuple
+
+class Response:
+    backend: Any
+    _exc: Optional[Exception]
+    from_addr: Optional[str]
+    to_addrs: Optional[List[str]]
+    _finished: bool
+    def __init__(self, exception: Optional[Exception] = ..., backend: Any = ...) -> None: ...
+    def set_exception(self, exc: Exception) -> None: ...
+    def raise_if_needed(self) -> None: ...
+    @property
+    def error(self) -> Optional[Exception]: ...
+    @property
+    def success(self) -> bool: ...
+
+class SMTPResponse(Response):
+    responses: List[Any]
+    esmtp_opts: Optional[List[str]]
+    rcpt_options: Optional[List[str]]
+    status_code: Optional[int]
+    status_text: Optional[str]
+    last_command: Optional[str]
+    refused_recipient: Dict[str, Any]
+    refused_recipients: Dict[str, Any]
+    def __init__(self, exception: Optional[Exception] = ..., backend: Any = ...) -> None: ...
+    def set_status(self, command: str, code: int, text: str, **kwargs: Any) -> None: ...

emails/backend/smtp/__init__.pyi

@@ -0,0 +1 @@
+from .backend import SMTPBackend as SMTPBackend

emails/backend/smtp/backend.pyi

@@ -0,0 +1,25 @@
+from typing import Any, Optional, Dict, List, Type, Callable
+from ..response import SMTPResponse
+from .client import SMTPClientWithResponse, SMTPClientWithResponse_SSL
+
+class SMTPBackend:
+    DEFAULT_SOCKET_TIMEOUT: int
+    connection_cls: Type[SMTPClientWithResponse]
+    connection_ssl_cls: Type[SMTPClientWithResponse_SSL]
+    response_cls: Type[SMTPResponse]
+    smtp_cls: Type[Any]
+    ssl: bool
+    tls: Optional[bool]
+    smtp_cls_kwargs: Dict[str, Any]
+    host: Optional[str]
+    port: Optional[int]
+    fail_silently: bool
+    mail_options: List[str]
+    _client: Optional[Any]
+
+    def __init__(self, ssl: bool = ..., fail_silently: bool = ..., mail_options: Optional[List[str]] = ..., **kwargs: Any) -> None: ...
+    def get_client(self) -> Any: ...
+    def close(self) -> None: ...
+    def make_response(self, exception: Optional[Exception] = ...) -> SMTPResponse: ...
+    def retry_on_disconnect(self, func: Callable[..., Any]) -> Callable[..., Any]: ...
+    def _send(self, **kwargs: Any) -> Any: ...

emails/backend/smtp/client.pyi

@@ -0,0 +1,34 @@
+from typing import Any, Union, Sequence
+from smtplib import SMTP, SMTP_SSL
+
+class SMTPClientWithResponse(SMTP):
+    parent: Any
+    make_response: Any
+    tls: bool
+    ssl: bool
+    debug: int
+    # user: str
+    # password: str
+    _initialized: bool
+    initialized: bool
+    def __init__(self, parent: Any, **kwargs: Any) -> None: ...
+    def initialize(self) -> None: ...
+    def quit(self) -> Any: ...
+    def _rset(self) -> None: ...
+    def sendmail(self, from_addr: str, to_addrs: Union[str, Sequence[str]], msg: Any, mail_options: Sequence[str] = ..., rcpt_options: Sequence[str] = ...) -> Any: ...
+
+class SMTPClientWithResponse_SSL(SMTP_SSL):
+    parent: Any
+    make_response: Any
+    tls: bool
+    ssl: bool
+    debug: int
+    # user: str
+    # password: str
+    _initialized: bool
+    initialized: bool
+    def __init__(self, parent: Any, **kwargs: Any) -> None: ...
+    def initialize(self) -> None: ...
+    def quit(self) -> Any: ...
+    def _rset(self) -> None: ...
+    def sendmail(self, from_addr: str, to_addrs: Union[str, Sequence[str]], msg: Any, mail_options: Sequence[str] = ..., rcpt_options: Sequence[str] = ...) -> Any: ...

emails/django/__init__.pyi

@@ -0,0 +1,17 @@
+from typing import Any, Optional, List, Union, Dict
+from ..message import MessageTransformerMixin, MessageSignMixin, MessageBuildMixin, BaseMessage
+
+class DjangoMessageMixin:
+    _recipients: Optional[List[str]]
+    _from_email: Optional[str]
+    @property
+    def encoding(self) -> str: ...
+    def recipients(self) -> List[str]: ...
+    @property
+    def from_email(self) -> str: ...
+    def _set_emails(self, mail_to: Optional[Union[str, List[str]]] = ..., set_mail_to: bool = ..., mail_from: Optional[str] = ..., set_mail_from: bool = ..., to: Optional[Union[str, List[str]]] = ...) -> None: ...
+    def send(self, mail_to: Optional[Union[str, List[str]]] = ..., set_mail_to: bool = ..., mail_from: Optional[str] = ..., set_mail_from: bool = ..., context: Optional[Dict[str, Any]] = ..., connection: Optional[Any] = ..., to: Optional[Union[str, List[str]]] = ...) -> Any: ...
+
+class DjangoMessage(DjangoMessageMixin, MessageTransformerMixin, MessageSignMixin, MessageBuildMixin, BaseMessage): ...
+
+Message = DjangoMessage

emails/django_.pyi

@@ -0,0 +1 @@
+from .django import *

emails/exc.pyi

@@ -0,0 +1,5 @@
+from .packages.dkim import DKIMException as DKIMException
+
+class HTTPLoaderError(Exception): ...
+class BadHeaderError(ValueError): ...
+class IncompleteMessage(ValueError): ...

emails/loader/__init__.pyi

@@ -0,0 +1,9 @@
+from typing import Any, Optional, Dict, Type, List
+from .local_store import FileSystemLoader as FileSystemLoader, ZipLoader as ZipLoader, MsgLoader as MsgLoader, FileNotFound as FileNotFound
+from .helpers import guess_charset as guess_charset
+
+class LoadError(Exception): ...
+class IndexFileNotFound(LoadError): ...
+class InvalidHtmlFile(LoadError): ...
+
+def from_html(html: str, text: Optional[str] = ..., base_url: Optional[str] = ..., message_params: Optional[Dict[str, Any]] = ..., local_loader: Optional[Any] = ..., template_cls: Optional[Type[Any]] = ..., message_cls: Optional[Type[Any]] = ..., source_filename: Optional[str] = ..., requests_params: Optional[Dict[str, Any]] = ..., **kwargs: Any) -> Any: ...

emails/loader/helpers.pyi

@@ -0,0 +1,24 @@
+from typing import Any, Optional, List, Tuple, Union, Pattern
+
+class ReRules:
+    re_meta: Pattern[Any]
+    re_is_http_equiv: Pattern[Any]
+    re_parse_http_equiv: Pattern[Any]
+    re_charset: Pattern[Any]
+    def __init__(self, conv: Optional[Any] = ...) -> None: ...
+
+RULES_U: ReRules
+RULES_B: ReRules
+
+def guess_text_charset(text: Union[str, bytes], is_html: bool = ...) -> Optional[str]: ...
+def guess_html_charset(html: Union[str, bytes]) -> Optional[str]: ...
+def guess_charset(headers: Any, html: Union[str, bytes]) -> Optional[str]: ...
+
+COMMON_CHARSETS: Tuple[str, ...]
+
+def decode_text(text: Union[str, bytes],
+                is_html: bool = ...,
+                guess_charset: bool = ...,
+                try_common_charsets: bool = ...,
+                charsets: Optional[List[str]] = ...,
+                fallback_charset: str = ...) -> Tuple[str, Optional[str]]: ...

emails/loader/local_store.pyi

@@ -0,0 +1,51 @@
+from typing import Any, Optional, List, Tuple, Union, Iterator
+# from .helpers import decode_text
+
+class FileNotFound(Exception): ...
+
+def split_template_path(template: str) -> List[str]: ...
+def open_if_exists(filename: str, mode: str = ...) -> Optional[Any]: ...
+
+class BaseLoader:
+    def __getitem__(self, filename: str) -> Optional[bytes]: ...
+    def get_file(self, name: str) -> Tuple[Optional[bytes], Optional[float]]: ...
+    def list_files(self) -> Iterator[str]: ...
+    def content(self, filename: str, is_html: bool = ..., decode: bool = ..., guess_charset: bool = ..., charset: str = ...) -> Union[str, bytes, None]: ...
+    def find_index_file(self, filename: Optional[str] = ..., extensions: Tuple[str, ...] = ..., stop_names: Tuple[str, ...] = ..., raise_if_not_found: bool = ...) -> Optional[str]: ...
+
+class FileSystemLoader(BaseLoader):
+    searchpath: List[str]
+    encoding: str
+    base_path: Optional[str]
+    def __init__(self, searchpath: Union[str, List[str]], encoding: str = ..., base_path: Optional[str] = ...) -> None: ...
+    def get_file(self, name: str) -> Tuple[Optional[bytes], Optional[float]]: ...
+    def list_files(self) -> Iterator[str]: ...
+
+class ZipLoader(BaseLoader):
+    zipfile: Any
+    encoding: str
+    base_path: Optional[str]
+    _decoded_filenames: Optional[Any]
+    _original_filenames: Optional[Any]
+    def __init__(self, file: Any, encoding: str = ..., base_path: Optional[str] = ...) -> None: ...
+    def get_file(self, name: str) -> Tuple[Optional[bytes], Optional[float]]: ...
+    def list_files(self) -> Iterator[str]: ...
+
+class MsgLoader(BaseLoader):
+    msg: Any
+    base_path: Optional[str]
+    _html_parts: List[Any]
+    _text_parts: List[Any]
+    _files: Any
+    _content_ids: Any
+    _parsed: bool
+    headers: Any
+    def __init__(self, msg: Any, base_path: Optional[str] = ...) -> None: ...
+    def get_file(self, name: str) -> Tuple[Optional[bytes], Optional[float]]: ...
+    def list_files(self) -> Iterator[str]: ...
+    @property
+    def attachments(self) -> Any: ...
+    @property
+    def html(self) -> Any: ...
+    @property
+    def text(self) -> Any: ...

emails/message.pyi

@@ -0,0 +1,160 @@
+from typing import Any, Optional, Union, Tuple, List, Dict, Callable, Set, Type
+from .store import BaseFile, MemoryFileStore
+from .signers import DKIMSigner
+from .backend import ObjectFactory, SMTPBackend
+from .transformer import MessageTransformer
+
+class BaseMessage:
+    attachment_cls: Type[BaseFile]
+    filestore_cls: Type[MemoryFileStore]
+    policy: Any
+    _attachments: Optional[MemoryFileStore]
+    charset: str
+    headers_encoding: str
+    _message_id: Union[str, Callable[[], str], None]
+    render_data: Dict[str, Any]
+    _mail_from: Optional[Tuple[str, str]]
+    _mail_to: List[Tuple[str, str]]
+    _cc: List[Tuple[str, str]]
+    _bcc: List[Tuple[str, str]]
+    _headers: Dict[str, Any]
+    _html: Any
+    _html_url: Optional[str]
+    _text: Any
+    _text_url: Optional[str]
+    _subject: Optional[str]
+    _date: Union[str, Callable[[], str], bool, None]
+
+    def __init__(self,
+                 charset: str = ...,
+                 message_id: Union[str, Callable[[], str], None] = ...,
+                 date: Union[str, Callable[[], str], bool, None] = ...,
+                 subject: Optional[str] = ...,
+                 mail_from: Union[str, Tuple[str, str], None] = ...,
+                 mail_to: Union[str, List[str], Tuple[str, str], List[Tuple[str, str]], None] = ...,
+                 headers: Optional[Dict[str, Any]] = ...,
+                 html: Any = ...,
+                 text: Any = ...,
+                 attachments: Optional[List[Any]] = ...,
+                 cc: Union[str, List[str], Tuple[str, str], List[Tuple[str, str]], None] = ...,
+                 bcc: Union[str, List[str], Tuple[str, str], List[Tuple[str, str]], None] = ...,
+                 headers_encoding: Optional[str] = ...) -> None: ...
+
+    def set_mail_from(self, mail_from: Union[str, Tuple[str, str], None]) -> None: ...
+    def get_mail_from(self) -> Optional[Tuple[str, str]]: ...
+    mail_from: Optional[Tuple[str, str]]
+
+    def set_mail_to(self, mail_to: Union[str, List[str], Tuple[str, str], List[Tuple[str, str]], None]) -> None: ...
+    def get_mail_to(self) -> List[Tuple[str, str]]: ...
+    mail_to: List[Tuple[str, str]]
+
+    def set_cc(self, addr: Union[str, List[str], Tuple[str, str], List[Tuple[str, str]], None]) -> None: ...
+    def get_cc(self) -> List[Tuple[str, str]]: ...
+    cc: List[Tuple[str, str]]
+
+    def set_bcc(self, addr: Union[str, List[str], Tuple[str, str], List[Tuple[str, str]], None]) -> None: ...
+    def get_bcc(self) -> List[Tuple[str, str]]: ...
+    bcc: List[Tuple[str, str]]
+
+    def get_recipients_emails(self) -> List[str]: ...
+    def set_headers(self, headers: Optional[Dict[str, Any]]) -> None: ...
+
+    def set_html(self, html: Any, url: Optional[str] = ...) -> None: ...
+    def get_html(self) -> Any: ...
+    html: Any
+
+    def set_text(self, text: Any, url: Optional[str] = ...) -> None: ...
+    def get_text(self) -> Any: ...
+    text: Any
+
+    @property
+    def html_body(self) -> Any: ...
+    @property
+    def text_body(self) -> Any: ...
+
+    def set_subject(self, value: Optional[str]) -> None: ...
+    def get_subject(self) -> Optional[str]: ...
+    subject: Optional[str]
+
+    def render(self, **kwargs: Any) -> None: ...
+
+    def set_date(self, value: Union[str, Callable[[], str], bool, None]) -> None: ...
+    def get_date(self) -> Optional[str]: ...
+    date: Optional[str]
+    message_date: Optional[str]
+
+    @property
+    def message_id(self) -> Optional[str]: ...
+    @message_id.setter
+    def message_id(self, value: Union[str, Callable[[], str], None]) -> None: ...
+
+    @property
+    def attachments(self) -> MemoryFileStore: ...
+    def attach(self, **kwargs: Any) -> None: ...
+
+class MessageBuildMixin:
+    ROOT_PREAMBLE: str
+    ADDRESS_HEADERS: Set[str]
+    before_build: Optional[Callable[[Any], None]]
+    after_build: Optional[Callable[[Any, Any], None]]
+
+    def encode_header(self, value: Any) -> Any: ...
+    def encode_address_header(self, pair: Optional[Tuple[str, str]]) -> Optional[str]: ...
+    encode_name_header: Callable[[Optional[Tuple[str, str]]], Optional[str]]
+    def set_header(self, msg: Any, key: str, value: Any, encode: bool = ...) -> None: ...
+    def _build_root_message(self, message_cls: Optional[Type[Any]] = ..., **kw: Any) -> Any: ...
+    def _build_html_part(self) -> Any: ...
+    def _build_text_part(self) -> Any: ...
+    def build_message(self, message_cls: Optional[Type[Any]] = ...) -> Any: ...
+    _build_message: Callable[[Optional[Type[Any]]], Any]
+    def as_message(self, message_cls: Optional[Type[Any]] = ...) -> Any: ...
+    message: Callable[[Optional[Type[Any]]], Any]
+    def as_string(self, message_cls: Optional[Type[Any]] = ...) -> str: ...
+    def as_bytes(self, message_cls: Optional[Type[Any]] = ...) -> bytes: ...
+
+class MessageSendMixin:
+    smtp_pool_factory: Type[ObjectFactory]
+    smtp_cls: Type[SMTPBackend]
+    @property
+    def smtp_pool(self) -> ObjectFactory: ...
+    def send(self,
+             to: Union[str, List[str], Tuple[str, str], List[Tuple[str, str]], None] = ...,
+             set_mail_to: bool = ...,
+             mail_from: Union[str, Tuple[str, str], None] = ...,
+             set_mail_from: bool = ...,
+             render: Optional[Dict[str, Any]] = ...,
+             smtp_mail_options: Optional[Any] = ...,
+             smtp_rcpt_options: Optional[Any] = ...,
+             smtp: Union[Dict[str, Any], Any, None] = ...) -> Any: ...
+
+class MessageTransformerMixin:
+    transformer_cls: Optional[Type[MessageTransformer]]
+    _transformer: Optional[MessageTransformer]
+    def create_transformer(self, transformer_cls: Optional[Type[MessageTransformer]] = ..., **kw: Any) -> MessageTransformer: ...
+    def destroy_transformer(self) -> None: ...
+    @property
+    def transformer(self) -> MessageTransformer: ...
+    def transform(self, **kwargs: Any) -> None: ...
+
+class MessageSignMixin:
+    signer_cls: Type[DKIMSigner]
+    _signer: Optional[DKIMSigner]
+    def sign(self, **kwargs: Any) -> Any: ...
+    dkim: Callable[..., Any]
+    def sign_message(self, msg: Any) -> Any: ...
+    def sign_string(self, message_string: str) -> str: ...
+    def sign_bytes(self, message_bytes: bytes) -> bytes: ...
+
+class Message(MessageSendMixin, MessageTransformerMixin, MessageSignMixin, MessageBuildMixin, BaseMessage): ...
+
+def html(**kwargs: Any) -> Message: ...
+
+class DjangoMessageProxy:
+    _message: Message
+    _recipients: Optional[List[str]]
+    _context: Dict[str, Any]
+    from_email: str
+    encoding: str
+    def __init__(self, message: Message, recipients: Optional[List[str]] = ..., context: Optional[Dict[str, Any]] = ...) -> None: ...
+    def recipients(self) -> List[str]: ...
+    def message(self) -> Any: ...

emails/packages/dkim/__init__.pyi

@@ -0,0 +1,6 @@
+from typing import Any, Optional, Tuple, List, Union
+
+class DKIMException(Exception): ...
+class UnparsableKeyError(DKIMException): ...
+
+def sign(message: Union[str, bytes], selector: bytes, domain: bytes, privkey: bytes, identity: Optional[bytes] = ..., canonicalize: Tuple[bytes, bytes] = ..., signature_algorithm: bytes = ..., include_headers: Optional[List[str]] = ..., length: bool = ..., logger: Optional[Any] = ...) -> bytes: ...