Load auto responder from any python script with the defined interface. Improve documentation

Author: fkantelberg

README.md

@@ -13,6 +13,14 @@ like Thunderbird for more advanced usage.
 
 DO NOT USE FOR PRODUCTION.
 
+### Features
+
+- Generate random mails
+- Receive, send mails and reply to mails
+- Generate randomized mails
+- Manage IMAP flags and automated flagging
+- SMTP auto respond feature for automatic testing
+
 ### Supported
 
 - SMTP (optionally with STARTTLS)

src/mail_devel/automation/reply_always.py

@@ -0,0 +1,9 @@
+from email.message import Message
+from logging import Logger
+
+from mail_devel.builder import Builder
+from mail_devel.smtp import Reply
+
+
+def reply(message: Message, flags: set[str], _logger: Logger) -> Reply | None:
+    return Reply(Builder.reply_mail(message), flags - {"Seen"})

src/mail_devel/service.py

@@ -306,7 +306,10 @@ def parse(cls, args: list[str] | None = None) -> argparse.Namespace:
         )
         group.add_argument(
             "--smtp-responder",
-            help="Automatically respond to received mails",
+            help="Automatically respond to received mails. Possible options are "
+            "pre-defined scripts like reply_once or reply_always or a path to "
+            "python script with the defined reply() function. See the source of the "
+            "pre-defined scripts for the interface definition",
         )
 
         group = parser.add_argument_group("Options")

src/mail_devel/smtp.py

@@ -1,6 +1,9 @@
 import importlib
+import importlib.util
 import logging
+import os
 from email.message import Message
+from types import ModuleType
 from typing import Callable, Iterable, Type
 
 from aiosmtpd.handlers import AsyncMessage
@@ -56,18 +59,43 @@ def _convert_flags(
                 result.append(flag)
         return frozenset(result)
 
+    def _load_responder_from_file(self, responder: str) -> ModuleType | None:
+        if not os.path.isfile(responder):
+            return None
+
+        try:
+            spec = importlib.util.spec_from_file_location("autorespond", responder)
+            if not spec or not spec.loader:
+                return None
+
+            script = importlib.util.module_from_spec(spec)
+            if not script:
+                return None
+
+            spec.loader.exec_module(script)
+            return script
+        except ImportError:
+            return None
+
     def load_responder(self, responder: str | None = None) -> None:
         if not responder:
             return
 
         try:
             script = importlib.import_module(f".automation.{responder}", __package__)
+            _logger.info(f"Loaded auto responder .automation.{responder}")
         except ImportError:
-            return
+            script = None
+
+        if not script:
+            script = self._load_responder_from_file(responder)
+            if script:
+                _logger.info(f"Loaded auto responder {responder}")
 
-        reply = getattr(script, "reply", None)
-        if callable(reply):
-            self.responder = reply
+        if script:
+            reply = getattr(script, "reply", None)
+            if callable(reply):
+                self.responder = reply
 
     async def auto_respond(self, message: Message) -> None:
         if not callable(self.responder):