Add type hints for public API (#191)

Add type annotations to the public API surface:
- Message, html(), BaseMessage and all mixins
- SMTPBackend, Response, SMTPResponse
- DKIMSigner
- BaseFile, LazyHTTPFile, MemoryFileStore
- MessageID and utility functions

Add py.typed marker for PEP 561 compliance.

Author: lavr

emails/backend/response.py

@@ -1,58 +1,61 @@
 # encoding: utf-8
+from __future__ import annotations
 
+from typing import Any
 
-class Response(object):
 
-    def __init__(self, exception=None, backend=None):
+class Response:
+
+    def __init__(self, exception: Exception | None = None, backend: Any = None) -> None:
         self.backend = backend
         self.set_exception(exception)
-        self.from_addr = None
-        self.to_addrs = None
-        self._finished = False
+        self.from_addr: str | None = None
+        self.to_addrs: list[str] | None = None
+        self._finished: bool = False
 
-    def set_exception(self, exc):
+    def set_exception(self, exc: Exception | None) -> None:
         self._exc = exc
 
-    def raise_if_needed(self):
+    def raise_if_needed(self) -> None:
         if self._exc:
             raise self._exc
 
     @property
-    def error(self):
+    def error(self) -> Exception | None:
         return self._exc
 
     @property
-    def success(self):
+    def success(self) -> bool:
         return self._finished
 
 
 class SMTPResponse(Response):
 
-    def __init__(self, exception=None, backend=None):
+    def __init__(self, exception: Exception | None = None, backend: Any = None) -> None:
 
         super(SMTPResponse, self).__init__(exception=exception, backend=backend)
 
-        self.responses = []
+        self.responses: list[list] = []
 
-        self.esmtp_opts = None
-        self.rcpt_options = None
+        self.esmtp_opts: str | None = None
+        self.rcpt_options: str | None = None
 
-        self.status_code = None
-        self.status_text = None
-        self.last_command = None
-        self.refused_recipient = {}
+        self.status_code: int | None = None
+        self.status_text: str | None = None
+        self.last_command: str | None = None
+        self.refused_recipient: dict[str, tuple[int, str]] = {}
 
-    def set_status(self, command, code, text, **kwargs):
+    def set_status(self, command: str, code: int, text: str, **kwargs: Any) -> None:
         self.responses.append([command, code, text, kwargs])
         self.status_code = code
         self.status_text = text
         self.last_command = command
 
     @property
-    def success(self):
-        return self._finished and self.status_code and self.status_code == 250
+    def success(self) -> bool:
+        return self._finished and self.status_code is not None and self.status_code == 250
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return "<emails.backend.SMTPResponse status_code=%s status_text=%s>" % (self.status_code.__repr__(),
                                                                                 self.status_text.__repr__())
 

emails/backend/smtp/backend.py

@@ -1,7 +1,13 @@
 # encoding: utf-8
-import smtplib
+from __future__ import annotations
+
 import logging
+import smtplib
+from collections.abc import Callable
 from functools import wraps
+from types import TracebackType
+from typing import Any
+
 from ..response import SMTPResponse
 from .client import SMTPClientWithResponse, SMTPClientWithResponse_SSL
 from ...utils import DNS_NAME
@@ -13,7 +19,7 @@
 logger = logging.getLogger(__name__)
 
 
-class SMTPBackend(object):
+class SMTPBackend:
 
     """
     SMTPBackend manages a smtp connection.
@@ -25,7 +31,8 @@ class SMTPBackend(object):
     connection_ssl_cls = SMTPClientWithResponse_SSL
     response_cls = SMTPResponse
 
-    def __init__(self, ssl=False, fail_silently=True, mail_options=None, **kwargs):
+    def __init__(self, ssl: bool = False, fail_silently: bool = True,
+                 mail_options: list[str] | None = None, **kwargs: Any) -> None:
 
         self.smtp_cls = ssl and self.connection_ssl_cls or self.connection_cls
 
@@ -42,19 +49,19 @@ def __init__(self, ssl=False, fail_silently=True, mail_options=None, **kwargs):
 
         self.smtp_cls_kwargs = kwargs
 
-        self.host = kwargs.get('host')
-        self.port = kwargs.get('port')
+        self.host: str | None = kwargs.get('host')
+        self.port: int = kwargs.get('port')
         self.fail_silently = fail_silently
         self.mail_options = mail_options or []
 
-        self._client = None
+        self._client: SMTPClientWithResponse | None = None
 
-    def get_client(self):
+    def get_client(self) -> SMTPClientWithResponse:
         if self._client is None:
             self._client = self.smtp_cls(parent=self, **self.smtp_cls_kwargs)
         return self._client
 
-    def close(self):
+    def close(self) -> None:
 
         """
         Closes the connection to the email server.
@@ -70,12 +77,12 @@ def close(self):
             finally:
                 self._client = None
 
-    def make_response(self, exception=None):
+    def make_response(self, exception: Exception | None = None) -> SMTPResponse:
         return self.response_cls(backend=self, exception=exception)
 
-    def retry_on_disconnect(self, func):
+    def retry_on_disconnect(self, func: Callable[..., SMTPResponse]) -> Callable[..., SMTPResponse]:
         @wraps(func)
-        def wrapper(*args, **kwargs):
+        def wrapper(*args: Any, **kwargs: Any) -> SMTPResponse:
             try:
                 return func(*args, **kwargs)
             except smtplib.SMTPServerDisconnected:
@@ -85,7 +92,7 @@ def wrapper(*args, **kwargs):
                 return func(*args, **kwargs)
         return wrapper
 
-    def _send(self, **kwargs):
+    def _send(self, **kwargs: Any) -> SMTPResponse:
 
         response = None
         try:
@@ -106,7 +113,9 @@ def _send(self, **kwargs):
         else:
             return client.sendmail(**kwargs)
 
-    def sendmail(self, from_addr, to_addrs, msg, mail_options=None, rcpt_options=None):
+    def sendmail(self, from_addr: str, to_addrs: str | list[str],
+                 msg: Any, mail_options: list[str] | None = None,
+                 rcpt_options: list[str] | None = None) -> SMTPResponse | None:
 
         if not to_addrs:
             return None
@@ -127,8 +136,10 @@ def sendmail(self, from_addr, to_addrs, msg, mail_options=None, rcpt_options=Non
 
         return response
 
-    def __enter__(self):
+    def __enter__(self) -> SMTPBackend:
         return self
 
-    def __exit__(self, exc_type, exc_value, traceback):
+    def __exit__(self, exc_type: type[BaseException] | None,
+                 exc_value: BaseException | None,
+                 traceback: TracebackType | None) -> None:
         self.close()

emails/exc.py

@@ -1,4 +1,5 @@
 # encoding: utf-8
+from __future__ import annotations
 
 from .packages.dkim import DKIMException