PyEmailerAJM 1.8__tar.gz → 1.8.2__tar.gz

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

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: PyEmailerAJM
-Version: 1.8
+Version: 1.8.2
 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.2.tar.gz
 Author: Amcsparron
 Author-email: amcsparron@albanyny.gov
 License: MIT License

pyemailerajm-1.8.2/PyEmailerAJM/_version.py

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

pyemailerajm-1.8.2/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.2/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.2/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.2/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.2/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.2/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.2/PyEmailerAJM/continuous_monitor/backend/__init__.py

@@ -0,0 +1,6 @@
+from PyEmailerAJM.continuous_monitor.backend.email_state import EmailState
+from PyEmailerAJM.continuous_monitor.backend.continuous_colorizer import ContinuousColorizer
+from PyEmailerAJM.continuous_monitor.backend.snooze_tracking import SnoozeTracking
+from PyEmailerAJM.continuous_monitor.backend.continuous_monitor_base import ContinuousMonitorBase
+
+__all__ = ['EmailState','ContinuousColorizer', 'SnoozeTracking', 'ContinuousMonitorBase']

pyemailerajm-1.8.2/PyEmailerAJM/continuous_monitor/backend/continuous_colorizer.py

@@ -0,0 +1,138 @@
+from typing import Union, Tuple
+
+from ColorizerAJM import Colorizer
+
+from PyEmailerAJM.backend import AlertTypes
+
+
+class ContinuousColorizer(Colorizer):
+    """
+    Class providing functionality to handle and apply color coding for alert messages.
+    It extends functionality from the parent `Colorizer` class,
+    adding customized color management, HTML-based color translation,
+    and support for critical warning, overdue, and other alerts.
+
+    Attributes:
+      LIGHT_GRAY: ANSI escape code for light gray colored text.
+      DARK_GRAY: ANSI escape code for dark gray colored text.
+      ORANGE: ANSI escape code for orange colored text.
+      DARK_YELLOW: ANSI escape code for dark yellow colored text.
+
+    Methods:
+      __init__(**kwargs):
+        Initialize the OverdueColorizer with optional custom colors and specific default color assignments.
+
+      get_alert_color(alert: 'AlertTypes') -> str:
+        Return the appropriate color for a given alert type.
+
+      _populate_html(unpopulated_html: str, text_for_population: str) -> str:
+        Populate a provided HTML template with the given text before the closing '</span>' tag.
+
+      colorize(text: str, color: str or None = None, bold: bool = False, **kwargs) -> str:
+        Apply colorization to the provided text using ANSI escape codes or HTML formatting.
+
+      get_color_code(color: Union[str, dict, int, Tuple[int, int, int]], **kwargs) -> str:
+        Retrieve the processed color code either in plain format or as HTML, based on the settings.
+
+      translate_color_to_html(color_code: str) -> str:
+        Transform a color code into an HTML-compliant string using a `<span>` element.
+    """
+    ORANGE = '\x1b[33m'
+    DARK_YELLOW = '\x1b[220m'
+
+    def __init__(self, **kwargs):
+        custom_colors = kwargs.pop('custom_colors', {})
+        custom_colors.update({'ORANGE': self.__class__.ORANGE,
+                              # DARKGOLDENROD is the color name HTML will recognize
+                              'DARKGOLDENROD': self.__class__.DARK_YELLOW})
+        super().__init__(custom_colors=custom_colors, **kwargs)
+
+        self.overdue_color = self.get_color_code(self.__class__.RED, html_mode=True)
+        self.critical_warning_color = self.get_color_code(self.__class__.ORANGE, html_mode=True)
+        self.warning_color = self.get_color_code(self.__class__.DARK_YELLOW, html_mode=True)
+        self.other_color = self.get_color_code(self.__class__.WHITE, html_mode=True)
+
+    def get_alert_color(self, alert: 'AlertTypes'):
+        """
+        :param alert: The type of alert to determine the corresponding color.
+        :type alert: AlertTypes
+        :return: The color associated with the specified alert type.
+        :rtype: str
+        """
+        if alert == AlertTypes.WARNING:
+            return self.warning_color
+        elif alert == AlertTypes.CRITICAL_WARNING:
+            return self.critical_warning_color
+        elif alert == AlertTypes.OVERDUE:
+            return self.overdue_color
+        else:
+            return self.other_color
+
+    @staticmethod
+    def _populate_html(unpopulated_html: str, text_for_population: str):
+        """
+        :param unpopulated_html: HTML string that contains unpopulated sections marked by the closing '</span>' tag.
+        :type unpopulated_html: str
+        :param text_for_population: Text value to populate into the unpopulated HTML section before the closing '</span>' tag.
+        :type text_for_population: str
+        :return: A new HTML string with the text populated into the specified sections.
+        :rtype: str
+        """
+        return unpopulated_html.replace('</span>', f'{text_for_population}</span>')
+
+    def colorize(self, text, color=None, bold=False, **kwargs):
+        """
+        :param text: The text to be colorized.
+        :type text: str
+        :param color: The color to apply to the text. Defaults to None.
+        :type color: str or None
+        :param bold: A flag to indicate whether the text should be bold. Defaults to False.
+        :type bold: bool
+        :param kwargs: Additional optional parameters to control various aspects of the function. The 'html_mode' key can be used to specify whether HTML formatting is applied.
+        :return: The colorized text, optionally in HTML format if 'html_mode' is enabled in kwargs.
+        :rtype: str
+        """
+        html_mode = kwargs.get('html_mode', False)
+        if html_mode:
+            blank_html = self.translate_color_to_html(color)
+            colorized = self._populate_html(blank_html, text)
+        else:
+            colorized = super().colorize(text, color=color, bold=bold)
+        return colorized
+
+    def get_color_code(self, color: Union[str, dict, int, Tuple[int, int, int]], **kwargs) -> str:
+        """
+        :param color: The color input which can be a string, dictionary, integer, or a tuple representing RGB values.
+        :type color: Union[str, dict, int, Tuple[int, int, int]]
+        :param kwargs: Additional keyword arguments. Specifically, 'html_mode' can be passed to control whether the color code is translated to HTML.
+        :return: The processed color code as a string. If 'html_mode' is enabled, the color code is returned in HTML format, otherwise it's returned as is.
+        :rtype: str
+        """
+        html_mode = kwargs.get('html_mode', False)
+        if not color.startswith('\x1b') or not color.startswith('\033'):
+            cc = super().get_color_code(color)
+        else:
+            cc = color
+        if html_mode:
+            return self.translate_color_to_html(cc)
+        return cc
+
+    def translate_color_to_html(self, color_code: str):
+        """
+        Translate a specified color code to an HTML span element.
+
+        :param color_code: The color code in text representation. If the `color_code` starts with '<span',
+                           the method attempts to map it to corresponding custom or default color codes.
+                           If no mapping is found, an AttributeError is raised.
+        :type color_code: str
+        :return: The HTML span element string with the appropriate color style applied.
+        :rtype: str
+        """
+        if color_code.startswith('<span'):
+            new_color_code = [x[0] for x in {**self.custom_colors, **self.__class__.DEFAULT_COLOR_CODES}.items()
+                              if x[1] == color_code.split('color:')[1].split('">')[0]]
+            if new_color_code:
+                color_code = new_color_code[0]
+            else:
+                raise AttributeError(f'Could not translate color code: {color_code}')
+        return f'<span style="color:{color_code}"></span>'

pyemailerajm-1.8.2/PyEmailerAJM/continuous_monitor/backend/continuous_monitor_base.py

@@ -0,0 +1,114 @@
+from abc import abstractmethod
+from pathlib import Path
+from typing import TYPE_CHECKING, Optional
+
+from PyEmailerAJM import PyEmailer, is_instance_of_dynamic
+from PyEmailerAJM.backend import TheSandman
+from . import ContinuousColorizer, SnoozeTracking, EmailState
+
+if TYPE_CHECKING:
+    from PyEmailerAJM.backend import AlertTypes
+
+
+class ContinuousMonitorBase(PyEmailer, EmailState):
+    """
+    Class ContinuousMonitorBase provides functionality to initialize and manage continuous monitoring
+    with optional email notifications. It extends the PyEmailer and EmailState classes and incorporates helper
+    classes for additional functionalities.
+
+    Attributes:
+        ADMIN_EMAIL_LOGGER (list): A list to store administrator email loggers.
+        ADMIN_EMAIL (list): A list to store administrator email addresses.
+        ATTRS_TO_CHECK (list): A list of class attributes to validate during subclass initialization.
+
+    Methods:
+        __init__(display_window: bool, send_emails: bool, **kwargs):
+            Initializes an instance of ContinuousMonitorBase, setting up logging, helper classes,
+            and initial email configurations. This also checks for a development mode and applies any specified
+            behavior accordingly.
+
+        __init_subclass__(cls, **kwargs):
+            Validates certain class attributes for subclasses by ensuring their presence
+            and that they are non-empty lists.
+
+        check_for_class_attrs(cls, class_attrs_to_check):
+            Validates a list of class attributes to ensure they are defined, are lists,
+            and contain email addresses.
+
+        initialize_helper_classes(self, **kwargs):
+            Sets up and returns instances of helper classes including ContinuousColorizer, SnoozeTracking,
+            and TheSandman, each initialized with parameters from **kwargs.
+
+        log_dev_mode_warnings(self):
+            Logs warnings if the `dev_mode` attribute is set to True.
+
+        email_handler_init(self):
+            Configures the email handler unless running in development mode. Provides appropriate logging
+            based on the current mode.
+    """
+    ADMIN_EMAIL_LOGGER = []
+    ADMIN_EMAIL = []
+    ATTRS_TO_CHECK = []
+
+    def __init__(self, display_window: bool, send_emails: bool, **kwargs):
+        super().__init__(display_window, send_emails, **kwargs)
+
+        self.dev_mode = kwargs.get('dev_mode', False)
+        self.colorizer, self.snooze_tracker, self.sleep_timer = self.initialize_helper_classes(**kwargs)
+
+        self.log_dev_mode_warnings()
+        self.email_handler_init()
+
+    @classmethod
+    def check_for_class_attrs(cls, class_attrs_to_check):
+        for c in class_attrs_to_check:
+            if hasattr(cls, c) and isinstance(getattr(cls, c), list) and len(getattr(cls, c)) > 0:
+                continue
+            raise ValueError(f"{c} must be a list of email addresses")
+
+    def initialize_helper_classes(self, **kwargs):
+        colorizer = ContinuousColorizer(logger=self.logger)
+        snooze_tracker = SnoozeTracking(Path(kwargs.get('file_name', './snooze_tracker.json')),
+                                        logger=kwargs.get('logger', self.logger))
+        sleep_timer = TheSandman(sleep_time_seconds=kwargs.get('sleep_time_seconds', None), logger=self.logger)
+        return colorizer, snooze_tracker, sleep_timer
+
+    def log_dev_mode_warnings(self):
+        if self.dev_mode:
+            self.logger.warning("DEV MODE ACTIVATED!")
+            self.logger.warning(
+                f"WARNING: this is a DEVELOPMENT MODE emailer,"
+                f" it will mock send emails but not actually send them to {self.__class__.ADMIN_EMAIL}"
+            )
+
+    def email_handler_init(self):
+        if self.dev_mode:
+            self.logger.warning("email handler disabled for dev mode")
+        elif (not type(self).__name__ == "ContinuousMonitorAlertSend"
+              and not is_instance_of_dynamic(self, "__main__.ContinuousMonitorAlertSend")):
+            self.logger.warning(
+                f"email handler not initialized because this is not a ContinuousMonitorAlertSend subclass"
+            )
+        else:
+            self._elog.setup_email_handler(email_msg=self.email,
+                                           logger_admins=self.__class__.ADMIN_EMAIL_LOGGER)
+            self.email = self.initialize_new_email()
+            self.logger.info("email handler initialized, initialized a new email object for use by monitor")
+
+    def _print_and_postprocess(self, alert_level):
+        """
+        :param alert_level: The level of alert to be logged and potentially emailed.
+        :type alert_level
+        :return: None
+        :rtype: None
+        """
+        if not self.dev_mode:
+            self.logger.info(f"{alert_level} found!", print_msg=True)
+            self._postprocess_alert(alert_level)
+        else:
+            self.logger.info(f"{alert_level} found!", print_msg=True)
+            self.logger.warning("IS DEV MODE - NOT postprocessing")
+
+    @abstractmethod
+    def _postprocess_alert(self, alert_level: Optional['AlertTypes'] = None, **kwargs):
+        ...