magpie.api.notifications

Attributes

SMTPServerConfiguration

LOGGER

TEMPLATE_DIR

DEFAULT_TEMPLATE_MAPPING

Functions

get_email_template(→ mako.template.Template)

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

get_smtp_server_configuration(→ SMTPServerConfiguration)

Obtains and validates all required configuration parameters for SMTP server in order to send an email.

get_smtp_server_connection(→ Union[smtplib.SMTP, ...)

Obtains an opened connection to a SMTP server from application settings.

make_email_contents(→ magpie.typedefs.Str)

Generates the email contents using the template, substitution parameters, and the target email server configuration.

send_email(→ bool)

Send email notification using provided template and parameters.

Module Contents

magpie.api.notifications.SMTPServerConfiguration[source]
magpie.api.notifications.LOGGER[source]
magpie.api.notifications.TEMPLATE_DIR[source]
magpie.api.notifications.DEFAULT_TEMPLATE_MAPPING[source]
magpie.api.notifications.get_email_template(template_constant: magpie.typedefs.Str, container: magpie.typedefs.AnySettingsContainer | None = None) mako.template.Template[source]

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

Allowed values of template_constant are:

Raises:

IOError – if an explicit override value of the requested template cannot be located.

Returns:

template formatter from the requested template file.

magpie.api.notifications.get_smtp_server_configuration(settings: magpie.typedefs.SettingsType) SMTPServerConfiguration[source]

Obtains and validates all required configuration parameters for SMTP server in order to send an email.

magpie.api.notifications.get_smtp_server_connection(config: SMTPServerConfiguration) smtplib.SMTP | smtplib.SMTP_SSL[source]

Obtains an opened connection to a SMTP server from application settings.

If the connection is correctly instantiated, the returned SMTP server will be ready for sending emails.

magpie.api.notifications.make_email_contents(config: SMTPServerConfiguration, settings: magpie.typedefs.SettingsType, template: mako.template.Template, parameters: TemplateParameters | None = None) magpie.typedefs.Str[source]

Generates the email contents using the template, substitution parameters, and the target email server configuration.

magpie.api.notifications.send_email(recipient: magpie.typedefs.Str, container: magpie.typedefs.AnySettingsContainer, template: mako.template.Template, parameters: TemplateParameters | None = None) bool[source]

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.

Parameters:
  • recipient – Email address of the intended recipient to which the email must be sent.

  • template – Mako template used for the email contents.

  • container – Any container to retrieve application settings.

  • 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).