magpie.cli.send_email
=====================

.. py:module:: magpie.cli.send_email

.. autoapi-nested-parse::

   Sends email notification using SMTP connection defined from configuration.

   Useful for validation of SMTP settings retrieved from an INI file or debugging the rendered email contents.



Attributes
----------

.. autoapisummary::

   magpie.cli.send_email.DEFAULT_TEMPLATE_MAPPING
   magpie.cli.send_email.UserConfig
   magpie.cli.send_email.LOGGER


Classes
-------

.. autoapisummary::

   magpie.cli.send_email.EmailTemplateChoiceFormatter


Functions
---------

.. autoapisummary::

   magpie.cli.send_email.get_email_template
   magpie.cli.send_email.send_email
   magpie.cli.send_email.make_logging_options
   magpie.cli.send_email.setup_logger_from_options
   magpie.cli.send_email.get_logger
   magpie.cli.send_email.get_settings_from_config_ini
   magpie.cli.send_email.make_parser
   magpie.cli.send_email.main


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

.. py:data:: DEFAULT_TEMPLATE_MAPPING

.. py:function:: get_email_template(template_constant: magpie.typedefs.Str, container: Optional[magpie.typedefs.AnySettingsContainer] = None) -> mako.template.Template

   Retrieves the template file with email content matching the custom application setting or the corresponding default.

   Allowed values of :paramref:`template_constant` are:

       - :envvar:`MAGPIE_GROUP_TERMS_APPROVED_EMAIL_TEMPLATE`
       - :envvar:`MAGPIE_GROUP_TERMS_SUBMISSION_EMAIL_TEMPLATE`
       - :envvar:`MAGPIE_USER_REGISTRATION_SUBMISSION_EMAIL_TEMPLATE`
       - :envvar:`MAGPIE_USER_REGISTRATION_APPROVAL_EMAIL_TEMPLATE`
       - :envvar:`MAGPIE_USER_REGISTRATION_APPROVED_EMAIL_TEMPLATE`
       - :envvar:`MAGPIE_USER_REGISTRATION_DECLINED_EMAIL_TEMPLATE`
       - :envvar:`MAGPIE_USER_REGISTRATION_NOTIFY_EMAIL_TEMPLATE`

   :raises IOError: if an explicit override value of the requested template cannot be located.
   :returns: template formatter from the requested template file.


.. py:function:: send_email(recipient: magpie.typedefs.Str, container: magpie.typedefs.AnySettingsContainer, template: mako.template.Template, parameters: Optional[TemplateParameters] = None) -> bool

   Send email notification using provided template and parameters.

   The preparation steps of the email (retrieve SMTP configuration, setup the SMTP connection, define email content
   parameters and attempt template generation) will directly raise if invalid as they correspond to incorrect
   application code or configuration settings.

   Following step to send the email with the established SMTP connection is caught and logged if raising an exception.
   This is to allow the calling operation to ignore failing email notification and act accordingly using the resulting
   email status.

   :param recipient: Email address of the intended recipient to which the email must be sent.
   :param template: Mako template used for the email contents.
   :param container: Any container to retrieve application settings.
   :param parameters:
       Parameters to provide for templating email contents.
       They are applied on top of various defaults values provided to all emails.
   :raises: any SMTP server configuration, template generator or parameter parsing error for email setup.
   :returns: success status of the notification email (sent without error, no guarantee of reception).


.. py:function:: make_logging_options(parser: argparse.ArgumentParser) -> None

   Defines argument parser options for logging operations.


.. py:function:: setup_logger_from_options(logger: logging.Logger, args: argparse.Namespace) -> None

   Uses argument parser options to setup logging level from specified flags.

   Setup both the specific CLI logger that is provided and the generic `magpie` logger.


.. py:function:: get_logger(name: magpie.typedefs.Str, level: Optional[int] = None, force_stdout: bool = None, message_format: Optional[magpie.typedefs.Str] = None, datetime_format: Optional[magpie.typedefs.Str] = None) -> logging.Logger

   Immediately sets the logger level to avoid duplicate log outputs from the `root logger` and `this logger` when
   `level` is ``logging.NOTSET``.


.. py:function:: get_settings_from_config_ini(config_ini_path: magpie.typedefs.Str, ini_main_section_name: magpie.typedefs.Str = 'app:magpie_app') -> magpie.typedefs.SettingsType

.. py:data:: UserConfig

.. py:data:: LOGGER

.. py:class:: EmailTemplateChoiceFormatter(prog, indent_increment=2, max_help_position=24, width=None)

   Bases: :py:obj:`argparse.HelpFormatter`


   Formatter for generating usage messages and argument help strings.

   Only the name of this class is considered a public API. All the methods
   provided by the class are considered an implementation detail.


   .. py:method:: _format_action(action)

      Override the returned help message with available options and shortcuts for email template selection.



.. py:function:: make_parser() -> argparse.ArgumentParser

.. py:function:: main(args: Optional[Sequence[magpie.typedefs.Str]] = None, parser: Optional[argparse.ArgumentParser] = None, namespace: Optional[argparse.Namespace] = None) -> Any