Fix type hints, add mypy to CI, fix as_bytes DKIM bug (#194)

* Fix type hints issues from review

1. Include py.typed in published package: add package_data in
   setup.py and include in MANIFEST.in (without this, PEP 561
   support was not actually working)

2. Widen date callback type from Callable[[], str] to
   Callable[..., str | datetime | float] to match existing
   behavior (callbacks can return datetime/float, not just str)

3. Fix SMTPResponse annotations: esmtp_opts and rcpt_options are
   lists (not str), and rename refused_recipient to
   refused_recipients to match actual usage in client.py

* Add mypy type checking to CI

Configure mypy in setup.cfg with per-module overrides:
- emails.message: suppress mixin pattern false positives
- emails.packages: ignore vendored DKIM code
- emails.backend.smtp.client: private smtplib attrs
- emails.template, emails.django: optional deps

Add targeted type: ignore comments for known safe patterns.
Add tox typecheck environment and CI job.

mypy now passes clean on 26 source files.

* Fix mypy CI: add per-module ignore for requests stubs

The global ignore_missing_imports does not suppress import-untyped
for inline imports. Add explicit per-module override for requests.

* Remove redundant type annotations on property-backed attributes

The uri, filename, and data attributes are defined as properties
via get/set + property(). The type annotation in __init__ conflicted
with the property descriptor, causing mypy no-redef errors.
Removing the annotation lets mypy infer the type from the property.

* Replace getattr/hasattr with direct access and isinstance in BaseFile.get_data

Use self._data directly (type known from setter) and isinstance
checks that mypy can narrow, removing type: ignore comments.

* Reduce type: ignore comments from 26 to 14

Replace suppressions with proper fixes where possible:
- Use isinstance checks instead of hasattr for type narrowing
- Use assert for None-safety where input guarantees non-None
- Access self._data directly instead of getattr
- Remove redundant to_unicode calls on already-str values
- Use explicit if/else instead of tricky and/or expressions
- Use dict[] instead of .get() where key is guaranteed present

Remaining 14 ignores are genuine mypy limitations: vendored dkim
API, private stdlib attrs, intentional method overrides, and
decorator typing.

* Add tests for changed logic, fix as_bytes DKIM signing bug

New tests:
- BaseFile.get_data() with str, bytes, IO, and None
- SMTPResponse: defaults, set_status, success, refused_recipients
- Message.as_bytes() with DKIM signing

The as_bytes test uncovered a bug: as_bytes() called sign_string()
(expects str) instead of sign_bytes() (expects bytes), causing
TypeError when DKIM signing was enabled. Fixed.

* Fix SMTPResponse.status_text type: str → bytes

smtplib.SMTP.mail/rcpt/data return (int, bytes), so status_text
and the text parameter of set_status() should be bytes, not str.

* Reduce type: ignore from 14 to 5

- store/file.py: handle None payload explicitly, use get_mime_type()
  instead of super().mime_type, narrow LazyHTTPFile.get_data types
- signers.py: normalize privkey to bytes before parsing, use
  cast(bytes, ...) for vendored dkim.sign, rewrite sign methods
  with explicit if/else
- backend/smtp/client.py: add return type annotation for sendmail,
  add from __future__ import annotations
- backend/smtp/backend.py: remove no-any-return ignore (now typed
  via client.py), assert sendmail result is not None
- utils.py: add overloads for to_unicode, use cast(F, wrapper)
  for renderable decorator, build decode_header result with
  explicit loop and assert

Remaining 5 ignores are private API access (msg._headers,
email.utils internals), MIMEMixin inheritance, and a dead
code path in to_unicode.

* Simplify LazyHTTPFile.get_data control flow

* Simplify decode_header: remove to_native/to_unicode wrappers

Use direct isinstance check and bytes.decode() instead of
to_native/to_unicode. Clearer control flow, no type: ignore needed.

* Remove allow_none_charset from to_unicode

Dead code path: never called with allow_none_charset=True anywhere
in the codebase. It also violated its own return type (returned
bytes while promising str | None). Removing it simplifies the
function and eliminates the last type: ignore in to_unicode.

* Remove to_native/to_unicode calls from message, signers, utils

These were Python 2 compatibility helpers. On Python 3:
- to_native(s) where s is str → noop, removed
- to_native(s) where s is bytes → replaced with s.decode()
- to_unicode(s) where s is str → noop, removed
- to_unicode(value) for non-str → replaced with explicit
  bytes.decode() / str() branching

Functions kept in utils.py for now (still used by loader/).

* Remove to_bytes calls from signers.py

All inputs are known str — use .encode() directly instead of the
Python 2 compatibility wrapper. signers.py no longer imports
anything from utils.

* Remove assert in _send, let None propagate honestly

_send() can return None when client.sendmail() gets empty to_addrs.
Instead of asserting this away, widen the return type to
SMTPResponse | None and propagate through retry_on_disconnect
and sendmail.

* Replace cast with typed variable for dkim.sign result

Author: lavr

.github/workflows/tests.yaml

@@ -36,6 +36,24 @@ jobs:
       - name: run tests
         run: tox -e ${{ matrix.tox }} -- -m "not e2e"
 
+  typecheck:
+    name: "typecheck"
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+          cache: pip
+      - name: update pip
+        run: |
+          pip install -U wheel
+          pip install -U setuptools
+          python -m pip install -U pip
+      - run: pip install tox
+      - name: run mypy
+        run: tox -e typecheck
+
   e2e:
     name: "e2e / ${{ matrix.name }}"
     runs-on: ${{ matrix.os }}

MANIFEST.in

@@ -1 +1,2 @@
 include README.rst LICENSE requirements.txt
+include emails/py.typed

emails/__init__.py

@@ -42,7 +42,7 @@
 __license__ = 'Apache 2.0'
 __copyright__ = 'Copyright 2013-2026 Sergey Lavrinenko'
 
-USER_AGENT = 'python-emails/%s' % __version__
+USER_AGENT: str = 'python-emails/%s' % __version__
 
 from .message import Message, html
 from .utils import MessageID

emails/backend/response.py

@@ -37,15 +37,15 @@ def __init__(self, exception: Exception | None = None, backend: Any = None) -> N
 
         self.responses: list[list] = []
 
-        self.esmtp_opts: str | None = None
-        self.rcpt_options: str | None = None
+        self.esmtp_opts: list[str] | None = None
+        self.rcpt_options: list[str] | None = None
 
         self.status_code: int | None = None
-        self.status_text: str | None = None
+        self.status_text: bytes | None = None
         self.last_command: str | None = None
-        self.refused_recipient: dict[str, tuple[int, str]] = {}
+        self.refused_recipients: dict[str, tuple[int, bytes]] = {}
 
-    def set_status(self, command: str, code: int, text: str, **kwargs: Any) -> None:
+    def set_status(self, command: str, code: int, text: bytes, **kwargs: Any) -> None:
         self.responses.append([command, code, text, kwargs])
         self.status_code = code
         self.status_text = text

emails/backend/smtp/backend.py

@@ -34,7 +34,7 @@ class SMTPBackend:
     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
+        self.smtp_cls = self.connection_ssl_cls if ssl else self.connection_cls
 
         self.ssl = ssl
         self.tls = kwargs.get('tls')
@@ -50,7 +50,7 @@ def __init__(self, ssl: bool = False, fail_silently: bool = True,
         self.smtp_cls_kwargs = kwargs
 
         self.host: str | None = kwargs.get('host')
-        self.port: int = kwargs.get('port')
+        self.port: int = kwargs['port']  # always set as int two lines above
         self.fail_silently = fail_silently
         self.mail_options = mail_options or []
 
@@ -80,9 +80,9 @@ def close(self) -> None:
     def make_response(self, exception: Exception | None = None) -> SMTPResponse:
         return self.response_cls(backend=self, exception=exception)
 
-    def retry_on_disconnect(self, func: Callable[..., SMTPResponse]) -> Callable[..., SMTPResponse]:
+    def retry_on_disconnect(self, func: Callable[..., SMTPResponse | None]) -> Callable[..., SMTPResponse | None]:
         @wraps(func)
-        def wrapper(*args: Any, **kwargs: Any) -> SMTPResponse:
+        def wrapper(*args: Any, **kwargs: Any) -> SMTPResponse | None:
             try:
                 return func(*args, **kwargs)
             except smtplib.SMTPServerDisconnected:
@@ -92,7 +92,7 @@ def wrapper(*args: Any, **kwargs: Any) -> SMTPResponse:
                 return func(*args, **kwargs)
         return wrapper
 
-    def _send(self, **kwargs: Any) -> SMTPResponse:
+    def _send(self, **kwargs: Any) -> SMTPResponse | None:
 
         response = None
         try:
@@ -131,7 +131,7 @@ def sendmail(self, from_addr: str, to_addrs: str | list[str],
                         mail_options=mail_options or self.mail_options,
                         rcpt_options=rcpt_options)
 
-        if not self.fail_silently:
+        if response and not self.fail_silently:
             response.raise_if_needed()
 
         return response

emails/backend/smtp/client.py

@@ -1,10 +1,13 @@
 # encoding: utf-8
+from __future__ import annotations
+
 __all__ = ['SMTPClientWithResponse', 'SMTPClientWithResponse_SSL']
 
 import smtplib
-from smtplib import _have_ssl, SMTP
+from smtplib import _have_ssl, SMTP  # noqa: private API
 import logging
-from ... utils import sanitize_email
+from ..response import SMTPResponse
+from ...utils import sanitize_email
 
 logger = logging.getLogger(__name__)
 
@@ -55,7 +58,9 @@ def _rset(self):
         except smtplib.SMTPServerDisconnected:
             pass
 
-    def sendmail(self, from_addr, to_addrs, msg, mail_options=None, rcpt_options=None):
+    def sendmail(self, from_addr: str, to_addrs: list[str] | str,
+                 msg: bytes, mail_options: list[str] | None = None,
+                 rcpt_options: list[str] | None = None) -> SMTPResponse | None:
 
         if not to_addrs:
             return None

emails/message.py

@@ -6,7 +6,7 @@
 from email.utils import getaddresses
 from typing import Any, IO
 
-from .utils import (formataddr, to_unicode, to_native,
+from .utils import (formataddr,
                     SafeMIMEText, SafeMIMEMultipart, sanitize_address,
                     parse_name_and_email, load_email_charsets,
                     encode_header as encode_header_,
@@ -39,7 +39,7 @@ class BaseMessage:
     def __init__(self,
                  charset: str | None = None,
                  message_id: str | MessageID | bool | None = None,
-                 date: str | datetime | float | bool | Callable[[], str] | None = None,
+                 date: str | datetime | float | bool | Callable[..., str | datetime | float] | None = None,
                  subject: str | None = None,
                  mail_from: _Address = None,
                  mail_to: _AddressList = None,
@@ -158,7 +158,7 @@ def get_subject(self) -> str | None:
     def render(self, **kwargs: Any) -> None:
         self.render_data = kwargs
 
-    def set_date(self, value: str | datetime | float | bool | Callable[[], str] | None) -> None:
+    def set_date(self, value: str | datetime | float | bool | Callable[..., str | datetime | float] | None) -> None:
         self._date = value
 
     def get_date(self) -> str | None:
@@ -231,7 +231,7 @@ def set_header(self, msg: SafeMIMEMultipart, key: str,
             return
 
         if not isinstance(value, str):
-            value = to_unicode(value)
+            value = value.decode() if isinstance(value, bytes) else str(value)
 
         # Prevent header injection
         if '\n' in value or '\r' in value:
@@ -280,13 +280,15 @@ def _build_html_part(self) -> SafeMIMEText | None:
             p = SafeMIMEText(text, 'html', charset=self.charset)
             p.set_charset(self.charset)
             return p
+        return None
 
     def _build_text_part(self) -> SafeMIMEText | None:
         text = self.text_body
         if text:
             p = SafeMIMEText(text, 'plain', charset=self.charset)
             p.set_charset(self.charset)
             return p
+        return None
 
     def build_message(self, message_cls: type | None = None) -> SafeMIMEMultipart:
 
@@ -343,7 +345,7 @@ def as_string(self, message_cls: type | None = None) -> str:
         Note: this method costs one less message-to-string conversions
         for dkim in compare to self.as_message().as_string()
         """
-        r = to_native(self.build_message(message_cls=message_cls).as_string())
+        r = self.build_message(message_cls=message_cls).as_string()
         if self._signer:
             r = self.sign_string(r)
         return r
@@ -354,7 +356,7 @@ def as_bytes(self, message_cls: type | None = None) -> bytes:
         """
         r = self.build_message(message_cls=message_cls).as_bytes()
         if self._signer:
-            r = self.sign_string(r)
+            r = self.sign_bytes(r)
         return r
 
 

emails/signers.py

@@ -9,7 +9,6 @@
 from .packages import dkim
 from .packages.dkim import DKIMException, UnparsableKeyError
 from .packages.dkim.crypto import parse_pem_private_key
-from .utils import to_bytes, to_native
 
 
 class DKIMSigner:
@@ -28,27 +27,32 @@ def __init__(self, selector: str, domain: str, key: str | bytes | IO[bytes] | No
         if privkey and hasattr(privkey, 'read'):
             privkey = privkey.read()
 
+        # Normalize to bytes before parsing
+        privkey_bytes = privkey if isinstance(privkey, bytes) else str(privkey).encode()
+
         # Compile private key
         try:
-            privkey = parse_pem_private_key(to_bytes(privkey))
+            privkey_parsed = parse_pem_private_key(privkey_bytes)
         except UnparsableKeyError as exc:
             raise DKIMException(exc)
 
-        self._sign_params.update({'privkey': privkey,
-                                  'domain': to_bytes(domain),
-                                  'selector': to_bytes(selector)})
+        self._sign_params.update({'privkey': privkey_parsed,
+                                  'domain': domain.encode(),
+                                  'selector': selector.encode()})
 
     def get_sign_string(self, message: bytes) -> bytes | None:
         try:
             # pydkim module parses message and privkey on each signing
             # this is not optimal for mass operations
             # TODO: patch pydkim or use another signing module
-            return dkim.sign(message=message, **self._sign_params)
+            result: bytes = dkim.sign(message=message, **self._sign_params)
+            return result
         except DKIMException:
             if self.ignore_sign_errors:
                 logging.exception('Error signing message')
             else:
                 raise
+        return None
 
     def get_sign_bytes(self, message: bytes) -> bytes | None:
         return self.get_sign_string(message)
@@ -57,10 +61,11 @@ def get_sign_header(self, message: bytes) -> tuple[str, str] | None:
         # pydkim returns string, so we should split
         s = self.get_sign_string(message)
         if s:
-            (header, value) = to_native(s).split(': ', 1)
+            (header, value) = s.decode().split(': ', 1)
             if value.endswith("\r\n"):
                 value = value[:-2]
             return header, value
+        return None
 
     def sign_message(self, msg: MIMEMultipart) -> MIMEMultipart:
         """
@@ -71,9 +76,9 @@ def sign_message(self, msg: MIMEMultipart) -> MIMEMultipart:
         # but py3 smtplib requires str to send DATA command (#
         # so we have to convert msg.as_string
 
-        dkim_header = self.get_sign_header(to_bytes(msg.as_string()))
+        dkim_header = self.get_sign_header(msg.as_string().encode())
         if dkim_header:
-            msg._headers.insert(0, dkim_header)
+            msg._headers.insert(0, dkim_header)  # type: ignore[attr-defined]
         return msg
 
     def sign_message_string(self, message_string: str) -> str:
@@ -85,12 +90,16 @@ def sign_message_string(self, message_string: str) -> str:
         # but py3 smtplib requires str to send DATA command
         # so we have to convert message_string
 
-        s = self.get_sign_string(to_bytes(message_string))
-        return s and to_native(s) + message_string or message_string
+        s = self.get_sign_string(message_string.encode())
+        if s:
+            return s.decode() + message_string
+        return message_string
 
     def sign_message_bytes(self, message_bytes: bytes) -> bytes:
         """
         Insert DKIM header to message bytes
         """
         s = self.get_sign_bytes(message_bytes)
-        return s and to_bytes(s) + message_bytes or message_bytes
+        if s:
+            return s + message_bytes
+        return message_bytes

emails/store/file.py

@@ -29,16 +29,18 @@ class BaseFile:
     Store base "attachment-file" information.
     """
 
+    _data: bytes | str | IO[bytes] | None
+
     def __init__(self, **kwargs: Any) -> None:
         """
         uri and filename are connected properties.
         if no filename set, filename extracted from uri.
         if no uri, but filename set, then uri==filename
         """
-        self.uri: str | None = kwargs.get('uri', None)
+        self.uri = kwargs.get('uri', None)
         self.absolute_url: str | None = kwargs.get('absolute_url', None) or self.uri
-        self.filename: str | None = kwargs.get('filename', None)
-        self.data: bytes | str | IO[bytes] | None = kwargs.get('data', None)
+        self.filename = kwargs.get('filename', None)
+        self.data = kwargs.get('data', None)
         self._mime_type: str | None = kwargs.get('mime_type')
         self._headers: dict[str, str] = kwargs.get('headers', {})
         self._content_id: str | None = kwargs.get('content_id')
@@ -52,13 +54,13 @@ def as_dict(self, fields: tuple[str, ...] | None = None) -> dict[str, Any]:
         return dict([(k, getattr(self, k)) for k in fields])
 
     def get_data(self) -> bytes | str | None:
-        _data = getattr(self, '_data', None)
-        if isinstance(_data, str):
+        _data = self._data
+        if isinstance(_data, (str, bytes)):
             return _data
-        elif hasattr(_data, 'read'):
-            return _data.read()
+        elif _data is None:
+            return None
         else:
-            return _data
+            return _data.read()
 
     def set_data(self, value: bytes | str | IO[bytes] | None) -> None:
         self._data = value
@@ -142,7 +144,8 @@ def mime(self) -> MIMEBase | None:
         if p is None:
             filename_header = encode_header(self.filename)
             p = MIMEBase(*self.mime_type.split('/', 1), name=filename_header)
-            p.set_payload(to_bytes(self.data))
+            payload = to_bytes(self.data) or b''
+            p.set_payload(payload)
             encode_base64(p)
             if 'content-disposition' not in self._headers:
                 p.add_header('Content-Disposition', self.content_disposition, filename=filename_header)
@@ -186,7 +189,12 @@ def fetch(self) -> None:
 
     def get_data(self) -> bytes | str:
         self.fetch()
-        return self._data or ''
+        data = self._data
+        if data is None:
+            return ''
+        if isinstance(data, (str, bytes)):
+            return data
+        return data.read()
 
     def set_data(self, v: bytes | str | IO[bytes] | None) -> None:
         self._data = v
@@ -196,7 +204,7 @@ def set_data(self, v: bytes | str | IO[bytes] | None) -> None:
     @property
     def mime_type(self) -> str:
         self.fetch()
-        return super(LazyHTTPFile, self).mime_type
+        return self.get_mime_type()
 
     @property
     def headers(self) -> dict[str, str]:

emails/store/store.py

@@ -54,7 +54,7 @@ def remove(self, uri: BaseFile | str) -> None:
                 del self._filenames[filename]
             del self._files[uri]
 
-    def unique_filename(self, filename: str | None, uri: str | None = None) -> str:
+    def unique_filename(self, filename: str | None, uri: str | None = None) -> str | None:
 
         if filename in self._filenames:
             n = 1
@@ -66,7 +66,8 @@ def unique_filename(self, filename: str | None, uri: str | None = None) -> str:
                 if filename not in self._filenames:
                     break
 
-        self._filenames[filename] = uri
+        if filename is not None:
+            self._filenames[filename] = uri
 
         return filename
 
@@ -94,6 +95,7 @@ def by_filename(self, filename: str) -> BaseFile | None:
         uri = self._filenames.get(filename)
         if uri:
             return self.by_uri(uri)
+        return None
 
     def __getitem__(self, uri: str) -> BaseFile | None:
         return self.by_uri(uri) or self.by_filename(uri)