:py:mod:`eelib.utils.notification`
==================================

.. py:module:: eelib.utils.notification

.. autoapi-nested-parse::

   Sends notifications for the status of simulations.

   | Author: elenia@TUBS
   | Copyright 2024 elenia
   | This file is part of eELib, which is free software under the terms of the GNU GPL Version 3.



Module Contents
---------------

Classes
~~~~~~~

.. autoapisummary::

   eelib.utils.notification.Notifier
   eelib.utils.notification.EmailNotifier
   eelib.utils.notification.WebexNotifier
   eelib.utils.notification.StatusMonitor
   eelib.utils.notification.StatusMonitorEmail
   eelib.utils.notification.StatusMonitorWebex




Attributes
~~~~~~~~~~

.. autoapisummary::

   eelib.utils.notification._logger


.. py:data:: _logger

   

.. py:class:: Notifier


   Bases: :py:obj:`abc.ABC`

   Abstract parent class for notifier objects.

   .. py:method:: send_message(sim_identifier: str, success: bool, message: str = None, recipient_email: str = None)
      :abstractmethod:

      Abstract method for sending a message.

      :param sim_identifier: an identifier for the simulation.
      :type sim_identifier: str
      :param success: whether or not the simulation was successful.
      :type success: bool
      :param message: An additional message. Defaults to None.
      :type message: str
      :param recipient_email: the recipient email. Defaults to None.
      :type recipient_email: str


   .. py:method:: construct_message(sim_identifier: str, success: bool, message: str = None) -> tuple[str, str]

      Method to construct a message depending on success or failure of a simulation.

      :param sim_identifier: an identifier for the simulation.
      :type sim_identifier: str
      :param success: whether or not the simulation was successful.
      :type success: bool
      :param message: An additional message. Defaults to None.
      :type message: str

      :returns: the subject and content of the constructed message.
      :rtype: tuple[str, str]



.. py:class:: EmailNotifier(smtp_server: str = None, smtp_port: int = None, sender_email: str = None, sender_password: str = None)


   Bases: :py:obj:`Notifier`

   Class for sending notifications through email. Extends Notifier.

   .. py:attribute:: smtp_server

      

   .. py:attribute:: smtp_port

      

   .. py:attribute:: sender_email

      

   .. py:attribute:: sender_password

      

   .. py:method:: send_message(sim_identifier: str, success: bool, message: str = None, recipient_email: str = None)

      Sends email as a status update for a simulation.

      :param sim_identifier: an identifier for the simulation.
      :type sim_identifier: str
      :param success: whether or not the simulation was successful.
      :type success: bool
      :param message: An additional message. Defaults to None.
      :type message: str
      :param recipient_email: the recipient email. Defaults to None.
      :type recipient_email: str



.. py:class:: WebexNotifier(api_url: str = None, access_token: str = None)


   Bases: :py:obj:`Notifier`

   Class for sending notifications through Webex App. Extends Notifier.

   .. py:attribute:: access_token

      

   .. py:attribute:: url

      

   .. py:method:: send_message(sim_identifier: str, success: bool, message: str = None, recipient_email: str = None) -> list

      Sends webex message as a status update for a simulation.

      :param sim_identifier: an identifier for the simulation.
      :type sim_identifier: str
      :param success: whether or not the simulation was successful.
      :type success: bool
      :param message: An additional message. Defaults to None.
      :type message: str
      :param recipient_email: the recipient's email. Defaults to None.
      :type recipient_email: str

      :returns: json-encoded content of response or None.
      :rtype: list



.. py:class:: StatusMonitor(notifier: Notifier, sim_identifier: str, recipient_email: str = None)


   Bases: :py:obj:`abc.ABC`

   Abstract parent class for a group of context manager classes.

   Monitors the status of simulation and informs the user about success or failure.
   Use in the following format:

   `with StatusMonitor(...):`
       `execute_simulation()`

   .. py:attribute:: notifier

      

   .. py:attribute:: sim_identifier

      

   .. py:attribute:: recipient_email
      :value: 'None'

      

   .. py:method:: __enter__()

      Called at the beginning of a with statement. Performs setup actions.


   .. py:method:: __exit__(exc_type: any, exc_val: any, exc_tb: any) -> bool

      Called at the end of a with statement. Performs teardown actions and handles exceptions.

      :param exc_type: The type of the exception if any.
      :type exc_type: any
      :param exc_val: The value of the exception (e.g., the exception instance) if any.
      :type exc_val: any
      :param exc_tb: A traceback object encapsulating the call stack at the point where the
                     exception occurred.
      :type exc_tb: any

      :returns: returns False to propogate the exception.
      :rtype: bool



.. py:class:: StatusMonitorEmail(sim_identifier: str, recipient_email: str = None, **kwargs)


   Bases: :py:obj:`StatusMonitor`

   context manager class used to notify user of a simulation's status through email.

   Extends StatusMonitor.
   Use in the following format:

   `with StatusMonitor(...):`
       `execute_simulation()`

   .. py:attribute:: smtp_server

      

   .. py:attribute:: smtp_port

      

   .. py:attribute:: sender_email

      

   .. py:attribute:: sender_password

      

   .. py:attribute:: email_sender

      


.. py:class:: StatusMonitorWebex(sim_identifier: str, recipient_email: str = None, **kwargs)


   Bases: :py:obj:`StatusMonitor`

   context manager class used to notify user of a simulation's status through Webex.

   Extends StatusMonitor.
   Use in the following format:

   `with StatusMonitor(...):`
       `execute_simulation()`

   .. py:attribute:: api_url

      

   .. py:attribute:: access_token

      

   .. py:attribute:: webex_sender