#30: Replaced docstring type hints with proper Pythonic ones in test suit (#31)

Author: GitRon

CHANGES.md

@@ -1,5 +1,8 @@
 # Changelog
 
+**2.6.3** (2025-05-09)
+  * Replaced docstring type hints with proper Pythonic ones in test suit
+
 **2.6.2** (2025-04-03)
   * Maintenance updates via ambient-package-update
 

django_pony_express/__init__.py

@@ -1,3 +1,3 @@
 """Class-based emails including a test suite for Django"""
 
-__version__ = "2.6.2"
+__version__ = "2.6.3"

django_pony_express/services/tests.py

@@ -1,6 +1,6 @@
 import re
 import warnings
-from typing import Optional
+from typing import Optional, Union
 
 from django.core import mail
 from django.core.mail import EmailMultiAlternatives
@@ -10,38 +10,38 @@
 class EmailTestService:
     _outbox = None
 
-    def _ensure_outbox_is_loaded(self):
+    def _ensure_outbox_is_loaded(self) -> None:
         """
         Ensures that the outbox attribute is set
         """
         if self._outbox is None:
             self.reload()
 
-    def reload(self):
+    def reload(self) -> None:
         """
         Loads the current _outbox inside an attribute of this class
         """
         self._outbox = mail.outbox
 
-    def empty(self):
+    def empty(self) -> None:
         """
         Empties the current outbox
-        :return:
         """
         mail.outbox = []
         self.reload()
 
-    def filter(self, to=None, cc=None, bcc=None, subject=None):
+    def filter(
+        self,
+        to: Optional[str] = None,
+        cc: Optional[str] = None,
+        bcc: Optional[str] = None,
+        subject: Union[str, re.Pattern, None] = None,
+    ) -> "EmailTestServiceQuerySet":
         """
         Searches in the _outbox for emails matching either to and/or subject.
         Returns a list of email objects
-        :param to: str
-        :param cc: str
-        :param bcc: str
-        :param subject: str | re.Pattern
-        :return: EmailTestService
         """
-        # Ensure that outbox is up-to-date
+        # Ensure that outbox is up to date
         self.reload()
 
         if not any([to, cc, bcc, subject]):
@@ -70,12 +70,11 @@ def filter(self, to=None, cc=None, bcc=None, subject=None):
 
         return EmailTestServiceQuerySet(matching_list=match_list)
 
-    def all(self):
+    def all(self) -> "EmailTestServiceQuerySet":
         """
         Loads all mails from the outbox inside the matching list
-        :return:
         """
-        # Ensure that outbox is up-to-date
+        # Ensure that outbox is up to date
         self.reload()
 
         # Load data to matching list
@@ -91,39 +90,33 @@ class EmailTestServiceMail(mail.EmailMultiAlternatives):
 
     _testcase = TestCase()  # Hacky way to get access to TestCase.assert* methods without deriving from TestCase
 
-    def _get_html_content(self):
+    def _get_html_content(self) -> Optional[str]:
         """
-        Ensure we just have found one element and then return HTML part of the email
-        :return: str
+        Ensure we just have found one element and then return the HTML part of the email
         """
         # Search for string
         if len(self.alternatives) > 0:
             return self.alternatives[0][0]
         return None
 
-    def _get_txt_content(self):
+    def _get_txt_content(self) -> str:
         """
-        Ensure we just have found one element and then return text part of the email
-        :return: str
+        Ensure we just have found one element and then return the text part of the email
         """
         # Search for string
         return self.body
 
-    def assert_subject(self, subject, msg=None):
+    def assert_subject(self, subject: str, msg: Optional[str] = None) -> None:
         """
         Searches in a given email inside the HTML AND TXT part for a given string
-        :param subject: str
-        :param msg: str
         """
 
-        # Assert expected subject is equal to the generated one
+        # Assert the expected subject is equal to the generated one
         self._testcase.assertEqual(subject, self.subject, msg=msg)
 
-    def assert_body_contains(self, search_str, msg=None):
+    def assert_body_contains(self, search_str: str, msg: Optional[str] = None) -> None:
         """
         Searches in a given email inside the HTML AND TXT part for a given string
-        :param search_str: str
-        :param msg: str
         """
 
         # TODO: use Django 5.2 `body_contains()` once we drop older versions
@@ -135,56 +128,55 @@ def assert_body_contains(self, search_str, msg=None):
         if html_content is not None:
             self._testcase.assertIn(search_str, html_content, msg=msg)
 
-    def assert_body_contains_not(self, search_str, msg=None):
+    def assert_body_contains_not(self, search_str: str, msg: Optional[str] = None) -> None:
         """
         Searches in a given email inside the HTML AND TXT part for a given string
-        :param search_str: str
-        :param msg: str
         """
 
-        # Assert string is contained in HTML part
+        # Assert string is contained in the HTML part
         self._testcase.assertNotIn(search_str, self._get_html_content(), msg=msg)
-        # Assert string is contained in TXT part
+        # Assert string is contained in the TXT part
         self._testcase.assertNotIn(search_str, self._get_txt_content(), msg=msg)
 
-    def assert_to_contains(self, *emails: list[str]):
+    def assert_to_contains(self, *emails: list[str]) -> None:
+        """
+        Searches in all given email for a specific email address in the "to"
+        """
         for email in emails:
             self._testcase.assertIn(email, self.to)
 
 
 class EmailTestServiceQuerySet(TestCase):
     _match_list = None
 
-    def __init__(self, matching_list=None):
+    def __init__(self, matching_list: Optional[list] = None) -> None:
         super().__init__()
         self._match_list = matching_list
         for email in self._match_list or []:
-            # Change the class of every EmailMultiAlternative instance, so that it points to
+            # Change the class of every EmailMultiAlternative instance so that it points to
             # our subclass, which has some additional assertion-methods.
             if isinstance(email, EmailMultiAlternatives):
                 email.__class__ = EmailTestServiceMail
 
-    def _get_html_content(self):
+    def _get_html_content(self) -> Optional[str]:
         """
-        Ensure we just have found one element and then return HTML part of the email
-        :return: str
+        Ensure we just have found one element and then return the HTML part of the email
         """
         self._validate_lookup_cache_contains_one_element()
         # Search for string
         if len(self[0].alternatives) > 0:
             return self[0].alternatives[0][0]
         return None
 
-    def _get_txt_content(self):
+    def _get_txt_content(self) -> str:
         """
-        Ensure we just have found one element and then return text part of the email
-        :return: str
+        Ensure we just have found one element and then return the text part of the email
         """
         # Search for string
         self._validate_lookup_cache_contains_one_element()
         return self[0].body
 
-    def _validate_lookup_cache_contains_one_element(self):
+    def _validate_lookup_cache_contains_one_element(self) -> None:
         """
         Ensures that in the cached lookup is exactly one element. Needed for full-text-search.
         """
@@ -193,7 +185,7 @@ def _validate_lookup_cache_contains_one_element(self):
         elif self.count() == 0:
             raise RuntimeError("Current lookup has zero matches so lookup does not make sense.")
 
-    def _ensure_matching_list_was_populated(self):
+    def _ensure_matching_list_was_populated(self) -> None:
         """
         Make sure that we queried at least once before working with the results
         """
@@ -202,56 +194,51 @@ def _ensure_matching_list_was_populated(self):
                 "Counting of matches called without previous query. Please call filter() or all() first."
             )
 
-    def one(self):
+    def one(self) -> bool:
         """
         Checks if the previous query returned exactly one element
-        :return: bool
         """
         return self.count() == 1
 
-    def count(self):
+    def count(self) -> int:
         """
         Returns the number of matches found by a previous call of `find()`
-        :return: int
         """
-        # Ensure is was queried before using results
+        # Ensure list was queried before using results
         self._ensure_matching_list_was_populated()
 
         # Count matches
         return len(self)
 
-    def first(self):
+    def first(self) -> EmailMultiAlternatives:
         """
         Returns the first found element
-        :return: EmailMultiAlternatives
         """
-        # Ensure is was queried before using results
+        # Ensure list was queried before using results
         self._ensure_matching_list_was_populated()
         return self[0] if self.count() > 0 else False
 
-    def last(self):
+    def last(self) -> EmailMultiAlternatives:
         """
         Returns the last found element
-        :return: EmailMultiAlternatives
         """
-        # Ensure is was queried before using results
+        # Ensure list was queried before using results
         self._ensure_matching_list_was_populated()
         return self[-1] if self.count() > 0 else False
 
     def assert_one(self, msg: Optional[str] = None):
         """
-        Makes an assertion to make sure queried element exists exactly once
+        Makes an assertion to make sure the queried element exists exactly once
         """
         self.assertEqual(self.one(), True, msg=msg)
 
-    def assert_quantity(self, target_quantity: str, msg: Optional[str] = None):
+    def assert_quantity(self, target_quantity: str, msg: Optional[str] = None) -> None:
         """
-        Makes an assertion to make sure that amount of queried mails are equal to `target_quantity`
-        :return:
+        Makes an assertion to make sure that the number of queried mails is equal to `target_quantity`
         """
         self.assertEqual(self.count(), target_quantity, msg=msg)
 
-    def assert_subject(self, subject: str, msg: Optional[str] = None):
+    def assert_subject(self, subject: str, msg: Optional[str] = None) -> None:
         """
         Searches in a given email inside the HTML AND TXT part for a given string
         """
@@ -263,7 +250,7 @@ def assert_subject(self, subject: str, msg: Optional[str] = None):
         self._validate_lookup_cache_contains_one_element()
         self[0].assert_subject(subject, msg)
 
-    def assert_body_contains(self, search_str: str, msg: Optional[str] = None):
+    def assert_body_contains(self, search_str: str, msg: Optional[str] = None) -> None:
         """
         Searches in a given email inside the HTML AND TXT part for a given string
         """
@@ -276,7 +263,7 @@ def assert_body_contains(self, search_str: str, msg: Optional[str] = None):
         self._validate_lookup_cache_contains_one_element()
         self[0].assert_body_contains(search_str, msg)
 
-    def assert_body_contains_not(self, search_str: str, msg: Optional[str] = None):
+    def assert_body_contains_not(self, search_str: str, msg: Optional[str] = None) -> None:
         """
         Searches in a given email inside the HTML AND TXT part for a given string
         """
@@ -289,8 +276,8 @@ def assert_body_contains_not(self, search_str: str, msg: Optional[str] = None):
         self._validate_lookup_cache_contains_one_element()
         self[0].assert_body_contains_not(search_str, msg)
 
-    def __getitem__(self, item):
+    def __getitem__(self, item) -> EmailTestServiceMail:
         return self._match_list.__getitem__(item)
 
-    def __len__(self):
+    def __len__(self) -> int:
         return self._match_list.__len__()