weaver.notify
=============

.. py:module:: weaver.notify






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

.. py:data:: LOGGER

.. py:function:: resolve_email_template(job: weaver.datatype.Job, settings: weaver.typedefs.SettingsType) -> mako.template.Template

   Finds the most appropriate Mako Template email notification file based on configuration and :term:`Job` context.

   The example template is used by default *ONLY* if the template directory was not overridden. If overridden, failing
   to match any of the template file locations will raise to report the issue instead of silently using the default.

   .. seealso::
       https://github.com/crim-ca/weaver/blob/master/weaver/wps_restapi/templates/notification_email_example.mako

   :raises IOError:
       If the template directory was configured explicitly, but cannot be resolved, or if any of the possible
       combinations of template file names cannot be resolved under that directory.
   :returns: Matched template instance based on resolution order as described in the documentation.


.. py:function:: notify_job_email(job: weaver.datatype.Job, to_email_recipient: str, container: weaver.typedefs.AnySettingsContainer) -> None

   Send email notification of a :term:`Job` status.


.. py:function:: get_crypto_key(settings: weaver.typedefs.SettingsType, salt: bytes, rounds: int) -> bytes

   Get the cryptographic key used for encoding and decoding the email.


.. py:function:: encrypt_email(email: str, settings: weaver.typedefs.SettingsType) -> str

.. py:function:: decrypt_email(email: str, settings: weaver.typedefs.SettingsType) -> str

.. py:function:: map_job_subscribers(job_body: weaver.typedefs.JSON, settings: weaver.typedefs.SettingsType) -> Optional[weaver.typedefs.ExecutionSubscribers]

   Converts the :term:`Job` subscribers definition submitted at execution into a mapping for later reference.

   The returned contents must be sorted in the relevant :term:`Job` object.
   For backward compatibility, ``notification_email`` directly provided at the root will be used if corresponding
   definitions were not provided for the corresponding subscriber email fields.


.. py:function:: send_job_notification_email(job: weaver.datatype.Job, task_logger: logging.Logger, settings: weaver.typedefs.SettingsType) -> None

   Sends a notification email about the execution status for the subscriber if requested during :term:`Job` submission.


.. py:function:: send_job_callback_request(job: weaver.datatype.Job, task_logger: logging.Logger, settings: weaver.typedefs.SettingsType) -> None

   Send a callback request about the execution status for the subscriber if requested at :term:`Job` execution.


.. py:function:: notify_job_subscribers(job: weaver.datatype.Job, task_logger: logging.Logger, settings: weaver.typedefs.SettingsType) -> None

   Send notifications to all requested :term:`Job` subscribers according to its current status.

   All notification operations must be implemented as non-raising.
   In case of error, the :term:`Job` logs will be updated with relevant error details and resume execution.