PyEmailerAJM 1.8__tar.gz → 1.8.1__tar.gz

{pyemailerajm-1.8 → pyemailerajm-1.8.1}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: PyEmailerAJM
-Version: 1.8
+Version: 1.8.1
 Summary: Allows for automating sending Email with the Outlook Desktop client. Future releases will add more client support
 Home-page: https://github.com/amcsparron2793-Water/PyEmailer
-Download-URL: https://github.com/amcsparron2793-Water/PyEmailer/archive/refs/tags/1.8.tar.gz
+Download-URL: https://github.com/amcsparron2793-Water/PyEmailer/archive/refs/tags/1.8.1.tar.gz
 Author: Amcsparron
 Author-email: amcsparron@albanyny.gov
 License: MIT License

pyemailerajm-1.8.1/PyEmailerAJM/_version.py

@@ -0,0 +1 @@
+__version__ = '1.8.1'

pyemailerajm-1.8.1/PyEmailerAJM/backend/__init__.py

@@ -0,0 +1,34 @@
+from PyEmailerAJM.backend.errs import *
+from PyEmailerAJM.backend.enums import BasicEmailFolderChoices, AlertTypes
+from PyEmailerAJM.backend.the_sandman import TheSandman
+from PyEmailerAJM.backend.logger import PyEmailerLogger
+import warnings
+import functools
+
+
+def deprecated(reason: str = ""):
+    """
+    Decorator that marks a function or method as deprecated.
+
+    :param reason: Optional message to explain what to use instead
+                   or when the feature will be removed.
+    """
+
+    def decorator(func):
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            message = f"Function '{func.__name__}' is deprecated."
+            if reason:
+                message += f" {reason}"
+            warnings.warn(message, category=DeprecationWarning, stacklevel=2)
+            return func(*args, **kwargs)
+
+        return wrapper
+
+    return decorator
+
+
+__all__ = ['deprecated', 'EmailerNotSetupError', 'InvalidAlertLevel',
+           'DisplayManualQuit', 'NoMessagesFetched',
+           'UnrecognizedEmailError', 'BasicEmailFolderChoices',
+           'AlertTypes', 'TheSandman', 'PyEmailerLogger']

pyemailerajm-1.8.1/PyEmailerAJM/backend/enums.py

@@ -0,0 +1,36 @@
+from enum import Enum, IntEnum
+
+
+class AlertTypes(Enum):
+    """
+    An enumeration to represent different alert types with associated integer values.
+
+    Attributes:
+        WARNING: An alert type indicating a warning with an associated value of 5.
+        CRITICAL_WARNING: An alert type indicating a critical warning with an associated value of 24.
+        OVERDUE: An alert type indicating an overdue alert with an associated value of 48.
+
+    Methods:
+        __str__: Returns the name of the alert type as a string.
+    """
+    WARNING = 5
+    CRITICAL_WARNING = 24
+    OVERDUE = 48
+
+    def __str__(self):
+        return self.name
+
+
+class BasicEmailFolderChoices(IntEnum):
+    INBOX = 6
+    SENT_ITEMS = 5
+    DRAFTS = 16
+    DELETED_ITEMS = 3
+    OUTBOX = 4
+
+    def __str__(self):
+        """Return the enum name as a string."""
+        return self.name
+
+    def __repr__(self):
+        return f"<{self.__class__.__name__}.{self.name} ({self.value})>"

pyemailerajm-1.8.1/PyEmailerAJM/backend/errs.py

@@ -0,0 +1,31 @@
+from typing import Optional
+
+# noinspection PyUnresolvedReferences
+from pywintypes import com_error
+
+
+class EmailerNotSetupError(Exception):
+    ...
+
+
+class DisplayManualQuit(Exception):
+    ...
+
+
+class InvalidAlertLevel(Exception):
+    DEFAULT_ERR_MSG = 'Invalid alert level: {}'
+
+    def __init__(self, msg: '_AlertMessageBase', **kwargs):
+        self.msg = msg
+        self.err_msg_str = kwargs.get('err_msg_str', self.DEFAULT_ERR_MSG.format(self.msg.ALERT_LEVEL))
+        super().__init__(self.err_msg_str)
+
+
+class NoMessagesFetched(Exception):
+    ...
+
+
+class UnrecognizedEmailError(com_error):
+    def __init__(self, err_msg: Optional[str] = None, **kwargs):
+        self.err_msg = err_msg
+        super().__init__(self.err_msg, **kwargs)

pyemailerajm-1.8.1/PyEmailerAJM/backend/logger.py

@@ -0,0 +1,94 @@
+from logging import Filter, DEBUG, ERROR, Handler, FileHandler, StreamHandler, Logger, WARNING
+from pathlib import Path
+from typing import Union
+
+from EasyLoggerAJM import EasyLogger, OutlookEmailHandler, StreamHandlerIgnoreExecInfo
+from PyEmailerAJM.msg import Msg
+from PyEmailerAJM import __project_name__, __project_root__
+
+
+class DupeDebugFilter(Filter):
+    PREFIXES_TO_IGNORE = ["FW:", "RE:"]
+
+    def __init__(self, name="DebugDedupeFilter"):
+        super().__init__(name)
+        self.logged_messages = set()
+
+    def _clean_str(self, in_str):
+        for x in self.__class__.PREFIXES_TO_IGNORE:
+            in_str = in_str.replace(x, '')
+        return in_str
+
+    def filter(self, record):
+        # We only log the message if it has not been logged before
+        if record.levelno != DEBUG:
+            return True
+        clean_msg = self._clean_str(record.msg)
+        if clean_msg not in list(self.logged_messages):
+            self.logged_messages.add(clean_msg)
+            return True
+        return False
+
+
+class PyEmailerLogger(EasyLogger):
+    ROOT_LOG_LOCATION_DEFAULT = Path(__project_root__, 'logs').resolve()
+
+    def __call__(self):
+        return self.logger
+
+    @staticmethod
+    def _add_dupe_debug_to_handler(handler: Handler):
+        dupe_debug_filter = DupeDebugFilter()
+        handler.addFilter(dupe_debug_filter)
+
+    def initialize_logger(self, logger=None, **kwargs) -> Union[Logger, '_EasyLoggerCustomLogger']:
+        self.logger = super().initialize_logger(logger=logger, **kwargs)
+        self.logger.propagate = False
+        return self.logger
+
+    def setup_email_handler(self, **kwargs):
+        """
+        Sets up the email handler for the logger using the OutlookEmailHandler.
+
+        :param kwargs: Keyword arguments to configure the email handler.
+                       - email_msg: Specifies the email message content (default: None).
+                       - logger_admins: Specifies the list of admin emails (default: None).
+        :return: None
+        :rtype: None
+        """
+        # noinspection PyTypeChecker
+        OutlookEmailHandler.VALID_EMAIL_MSG_TYPES = [Msg]
+        try:
+            # noinspection PyTypeChecker
+            email_handler = OutlookEmailHandler(email_msg=kwargs.get('email_msg', None),
+                                                project_name=self.project_name,
+                                                logger_dir_path=self.log_location,
+                                                recipient=kwargs.get('logger_admins', None))
+        except ValueError as e:
+            self.logger.error(e.args[0], exc_info=True)
+            raise e from None
+
+        email_handler.setLevel(ERROR)
+        email_handler.setFormatter(self.formatter)
+        self.logger.addHandler(email_handler)
+
+    def _add_filter_to_file_handler(self, handler: FileHandler):
+        self._add_dupe_debug_to_handler(handler)
+
+    def _add_filter_to_stream_handler(self, handler: StreamHandler):
+        self._add_dupe_debug_to_handler(handler)
+
+    @property
+    def project_name(self):
+        return super().project_name
+
+    @project_name.setter
+    def project_name(self, value):
+        if value is None:
+            value = __project_name__
+        super().__setattr__('_project_name', value)
+
+    def create_stream_handler(self, log_level_to_stream=WARNING, **kwargs):
+        stream_handler = kwargs.get('stream_handler_instance', StreamHandlerIgnoreExecInfo())
+        super().create_stream_handler(log_level_to_stream=log_level_to_stream,
+                                      stream_handler_instance=stream_handler, **kwargs)

pyemailerajm-1.8.1/PyEmailerAJM/backend/the_sandman.py

@@ -0,0 +1,91 @@
+from datetime import datetime
+from logging import getLogger
+from time import sleep
+from typing import Union, Optional
+
+
+class TheSandman:
+    """
+        A utility class to facilitate and log time delays with custom sleep durations.
+
+        Attributes:
+            DEFAULT_SLEEP_TIME_SECONDS (int): Default sleep duration in seconds if not specified.
+            sleep_time (int): Actual sleep time (in seconds) to be used by the instance.
+            sleep_time_string (str): Human-readable string representing the current sleep duration.
+            logger (Logger): Logging instance for logging messages related to sleep operations.
+
+        Methods:
+            sleep_time_string:
+                Property getter and setter for updating the human-readable sleep time string.
+
+            sleep_round():
+                Splits the sleep duration into two equal parts. It logs and prints messages depicting the current sleep state, including the remaining time, and sleeps for the given durations.
+    """
+    # default 600 secs = 10 minutes
+    DEFAULT_SLEEP_TIME_SECONDS = 600
+    DEFAULT_SNOOZE_EXPIRATION_LIMIT_HOURS = 24
+    SECONDS_IN_HOUR = 3600
+
+    def __init__(self, sleep_time_seconds=None, **kwargs):
+        self.snooze_expiration_limit_hours = kwargs.get('snooze_expiration_limit_hours',
+                                                        self.__class__.DEFAULT_SNOOZE_EXPIRATION_LIMIT_HOURS)
+        self.sleep_time: int = sleep_time_seconds or self.__class__.DEFAULT_SLEEP_TIME_SECONDS
+        self._is_time_remaining = False
+        self._sleep_time_string = None
+        self.logger: getLogger = kwargs.get('logger', getLogger(__name__))
+        self.sleep_time_string = self.sleep_time
+        self.logger.info(f'TheSandman initialized - sleep time set as {self.sleep_time_string}')
+
+    @property
+    def sleep_time_string(self):
+        return self._sleep_time_string
+
+    @sleep_time_string.setter
+    def sleep_time_string(self, value: int):
+        if self._is_time_remaining:
+            more = 'more'
+        else:
+            more = ''
+        if value >= 60:
+            self._sleep_time_string = f'sleeping for {value // 60} {more} minute(s)'
+        else:
+            self._sleep_time_string = f'sleeping for {value} {more} second(s)'
+
+    def sleep(self, sleep_time_seconds: int, **kwargs):
+        """
+        :param sleep_time_seconds: The number of seconds the function should pause execution.
+        :type sleep_time_seconds: int
+        :return: None
+        :rtype: None
+        """
+
+        self.sleep_time_string = self.sleep_time if not self._is_time_remaining else sleep_time_seconds
+        self.logger.info(self.sleep_time_string, **kwargs)
+        sleep(sleep_time_seconds)
+
+    def sleep_in_rounds(self, rounds=2, **kwargs):
+        """
+        :param rounds: Number of intervals in which the total sleep time is divided. Defaults to 2.
+        :type rounds: int
+        :return: None
+        :rtype: None
+
+        """
+        dev_mode = kwargs.pop('dev_mode', True)
+        print_msg = kwargs.pop('print_msg', True)
+        self._is_time_remaining = False
+        for sr in range(rounds):
+            if sr == rounds - 1:
+                self._is_time_remaining = True
+            self.sleep((self.sleep_time // rounds), print_msg=print_msg, **kwargs)
+
+    @classmethod
+    def is_snooze_expired(cls, snoozed_at: datetime, snooze_expiration_limit_hours: Optional[int] = None):
+        if not snooze_expiration_limit_hours:
+            snooze_expiration_limit_hours = cls.DEFAULT_SNOOZE_EXPIRATION_LIMIT_HOURS
+        snooze_expiration_limit_seconds = snooze_expiration_limit_hours * cls.SECONDS_IN_HOUR
+        time_since_snooze = (datetime.now() - snoozed_at)
+        if time_since_snooze.total_seconds() >= snooze_expiration_limit_seconds:
+            #print('msg_snoozed expired! Unsnoozing now!')
+            return True
+        return False

pyemailerajm-1.8.1/PyEmailerAJM/continuous_monitor/__init__.py

@@ -0,0 +1,4 @@
+from PyEmailerAJM.continuous_monitor.continuous_monitor import ContinuousMonitor
+from PyEmailerAJM.continuous_monitor.continuous_monitor_alert_send import ContinuousMonitorAlertSend
+
+__all__ = ['ContinuousMonitor', 'ContinuousMonitorAlertSend']

pyemailerajm-1.8.1/PyEmailerAJM/continuous_monitor/continuous_monitor.py

@@ -0,0 +1,88 @@
+from abc import abstractmethod
+from typing import Callable
+
+from PyEmailerAJM.backend import AlertTypes
+from PyEmailerAJM.continuous_monitor.backend.continuous_monitor_base import ContinuousMonitorBase
+from PyEmailerAJM.msg import MsgFactory
+
+
+class ContinuousMonitor(ContinuousMonitorBase):
+    TITLE_STRING = " Watching for emails with alerts in {} folder ".center(100, '*')
+    MSG_FACTORY_CLASS: MsgFactory = MsgFactory
+
+    def GetMessages(self, folder_index=None):
+        """
+        :param folder_index: Index of the folder from which messages are retrieved. Defaults to None if not specified.
+        :type folder_index: int, optional
+        :return: A list of sorted and filtered message objects, each containing an alert.
+        :rtype: list
+        """
+        msgs = super().GetMessages(folder_index)
+        sorted_msgs = [self.__class__.MSG_FACTORY_CLASS.get_msg(x, logger=self.logger, snooze_checker=self.snooze_tracker) for x in msgs]
+        alert_messages = [x for x in sorted_msgs if x is not None and x.msg_alert]
+        return alert_messages
+
+    def _set_args_for_endless_watch(self):
+        """
+        Sets specific arguments for the endless_watch process.
+
+        :return: None
+        :rtype: None
+        """
+        self.send_emails = False
+        self.auto_send = False
+        self.display_window = False
+
+    @abstractmethod
+    def _postprocess_alert(self, alert_level=None, **kwargs):
+        ...
+
+    def check_for_alerts(self):
+        """
+        Checks for emails in the specified folder and identifies if there are any alerts. Alerts,
+        if present, are categorized as overdue, warning, or critical warning, and are processed accordingly.
+        Then logs the result of the check.
+
+        :return: None
+        :rtype: None
+
+        """
+        self.logger.info("\nChecking for emails with an alert...", print_msg=True)
+        self.refresh_messages()
+        if self.has_overdue:
+            self._print_and_postprocess(AlertTypes.OVERDUE)
+
+        elif self.has_warning:
+            self._print_and_postprocess(AlertTypes.WARNING)
+
+        elif self.has_critical_warning:
+            self._print_and_postprocess(AlertTypes.CRITICAL_WARNING)
+
+        else:
+            self.logger.info(f"No emails with an alert detected in {self.read_folder}", print_msg=True)
+
+        self.snooze_tracker.snooze_msgs(self.all_messages)
+
+    def endless_watch(self, stop_condition: Callable[[], bool] = None):
+        if not self.dev_mode:
+            self._set_args_for_endless_watch()
+
+        stop_condition = stop_condition or (lambda: False)  # Default stop_condition
+        email_dir_name = self.read_folder.name if self.read_folder else None
+
+        self.logger.info(self.__class__.TITLE_STRING.format(email_dir_name), print_msg=True)
+
+        while not stop_condition():
+            try:
+                self.check_for_alerts()
+                self._was_refreshed = False
+                self.sleep_timer.sleep_in_rounds()
+            except KeyboardInterrupt:
+                self.logger.error("KeyboardInterrupt detected, exiting program.")
+                break
+
+
+if __name__ == '__main__':
+    ContinuousMonitor.MSG_FACTORY_CLASS.ALERT_SUBJECT_KEYWORDS = ['training']
+    cm = ContinuousMonitor(False, False, dev_mode=False, show_warning_logs_in_console=True, )
+    cm.endless_watch()

pyemailerajm-1.8.1/PyEmailerAJM/continuous_monitor/continuous_monitor_alert_send.py

@@ -0,0 +1,120 @@
+from typing import Optional
+
+from PyEmailerAJM.continuous_monitor import ContinuousMonitor
+
+NO_COLORIZER = False
+
+
+class ContinuousMonitorAlertSend(ContinuousMonitor):
+    ADMIN_EMAIL_LOGGER = []
+    ADMIN_EMAIL = []
+    DEFAULT_SUBJECT = "Email Alert"
+    DEFAULT_MSG_BODY = ("Dear {admin_email_names},\n\n"
+                        "There is an Email in the inbox that has an alert ({msg_tuple}). \n\n"
+                        "Thanks,\n"
+                        "{email_sender}")
+    ATTRS_TO_CHECK = ['ADMIN_EMAIL', 'ADMIN_EMAIL_LOGGER']
+
+    def __init__(self, display_window: bool, send_emails: bool, **kwargs):
+
+        super().__init__(display_window, send_emails, **kwargs)
+        if not self.dev_mode:
+            if type(self) is ContinuousMonitorAlertSend:
+                self.__class__.check_for_class_attrs(self.__class__.ATTRS_TO_CHECK)
+        else:
+            self.logger.warning(f"IS DEV MODE - NOT checking for class attributes "
+                                f"({', '.join(self.__class__.ATTRS_TO_CHECK)}) for ContinuousMonitorAlertSend")
+
+    def __init_subclass__(cls, **kwargs):
+        cls.check_for_class_attrs(cls.ATTRS_TO_CHECK)
+
+    def _set_args_for_endless_watch(self):
+        self.send_emails = True
+        self.auto_send = True
+        self.display_window = False
+        self.logger.debug("send_emails, auto_send, and display_window set to True for endless_watch()")
+
+    def SetupEmail(self, recipient: Optional[str] = None, subject: str = DEFAULT_SUBJECT,
+                   text: str = None, attachments: list = None, **kwargs):
+        """
+        :param recipient: Email recipient(s). If not provided, defaults to ADMIN_EMAIL or a semicolon-separated string of recipients in case of a list.
+        :type recipient: Optional[str]
+        :param subject: Subject of the email. Defaults to DEFAULT_SUBJECT.
+        :type subject: str
+        :param text: Body text of the email. If not provided, defaults to the response_body attribute.
+        :type text: str
+        :param attachments: A list of attachments to include in the email.
+        :type attachments: list
+        :param kwargs: Additional keyword arguments passed to the parent SetupEmail method.
+        :type kwargs: dict
+        :return: The resulting email setup performed by the superclass's SetupEmail method.
+        :rtype: Any
+        """
+        if not recipient:
+            recipient = self.__class__.ADMIN_EMAIL
+            if isinstance(recipient, list):
+                recipient = ' ;'.join(recipient)
+        if not text:
+            text = self.response_body
+        return super().SetupEmail(recipient=recipient, subject=subject,
+                                  text=text, attachments=attachments, **kwargs)
+
+    def get_response_body_alert_level(self, msg: '_AlertMsgBase'):
+        """
+        :param msg: The message object which contains the alert level information.
+        :type msg: _AlertMsgBase
+        :return: The alert level string, optionally colorized if coloring is enabled.
+        :rtype: str
+        """
+        if NO_COLORIZER:
+            self.logger.debug("colorizer not available, using plain text for alert level")
+            rb_alert_string = msg.__class__.ALERT_LEVEL.name
+        else:
+            self.logger.debug("colorizer available, using colorized alert level")
+            color = self.colorizer.get_alert_color(msg.__class__.ALERT_LEVEL)
+            rb_alert_string = self.colorizer.colorize(msg.__class__.ALERT_LEVEL.name,
+                                                      color=color,
+                                                      html_mode=True)
+        return rb_alert_string
+
+    @property
+    def email_signature(self):
+        return ('<br>'.join(super().email_signature.split('\n'))
+                if super().email_signature is not None else None)
+
+    @property
+    def response_body(self):
+        """
+        Processes and formats the response body by compiling alert messages and their corresponding alert levels,
+            then generating a formatted string containing a summary of these messages.
+
+        :return: Processed and formatted response body string
+        :rtype: str
+        """
+        alert_msgs = [(x.subject, self.get_response_body_alert_level(x)) for x in self.GetMessages()]
+        msg_tuple = ', '.join([' - '.join(x) for x in alert_msgs])
+        formatted_admin_email_names = ', '.join([x.split('@')[0] for
+                                                 x in self.__class__.ADMIN_EMAIL]
+                                                ).replace('\n', '<br>')
+        formatted_full_body = self.__class__.DEFAULT_MSG_BODY.format(email_sender=self.email_signature,
+                                                                     msg_tuple=msg_tuple,
+                                                                     admin_email_names=formatted_admin_email_names
+                                                                     ).replace('\n', '<br>')
+        return formatted_full_body
+
+    def _postprocess_alert(self, alert_level=None, **kwargs):
+        self.SendOrDisplay(**kwargs)
+
+    def refresh_messages(self):
+        self.SetupEmail()
+        super().refresh_messages()
+
+
+if __name__ == '__main__':
+    ContinuousMonitorAlertSend.MSG_FACTORY_CLASS.ALERT_SUBJECT_KEYWORDS = ['training']
+    ContinuousMonitorAlertSend.ADMIN_EMAIL = ['amcsparron@albanyny.gov']
+    ContinuousMonitorAlertSend.ADMIN_EMAIL_LOGGER = ContinuousMonitorAlertSend.ADMIN_EMAIL
+    cm = ContinuousMonitorAlertSend(False, False,
+                                    dev_mode=False,
+                                    show_warning_logs_in_console=True)  #, email_sig_filename='Andrew Full.txt')
+    cm.endless_watch()

pyemailerajm-1.8.1/PyEmailerAJM/msg/__init__.py

@@ -0,0 +1,5 @@
+# pylint: disable=cyclic-import, wrong-import-position
+from PyEmailerAJM.msg.msg import Msg, FailedMsg
+from PyEmailerAJM.msg.factory import MsgFactory
+
+__all__ = ['Msg', 'FailedMsg', 'MsgFactory']