magpie.api.notifications

Attributes

SMTPServerConfiguration
LOGGER
TEMPLATE_DIR
DEFAULT_TEMPLATE_MAPPING

Functions

get_constant(→ magpie.typedefs.SettingValue)	Search in order for matched value of constant_name:
get_logger(→ logging.Logger)	Immediately sets the logger level to avoid duplicate log outputs from the root logger and this logger when
get_magpie_url(→ magpie.typedefs.Str)	Obtains the configured Magpie URL entrypoint based on the various combinations of supported configuration settings.
get_settings(→ magpie.typedefs.SettingsType)	Retrieve application settings from a supported container.
raise_log(→ NoReturn)	Logs the provided message to the logger and raises the corresponding exception afterwards.
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.get_constant(constant_name: magpie.typedefs.Str, settings_container: magpie.typedefs.AnySettingsContainer | None = None, settings_name: magpie.typedefs.Str | None = None, default_value: magpie.typedefs.SettingValue | None = None, raise_not_set: bool = True, raise_missing: bool = True, print_missing: bool = False, empty_missing: bool = False) → magpie.typedefs.SettingValue

Search in order for matched value of constant_name:

1. search in MAGPIE_CONSTANTS

2. search in settings if specified

3. search alternative setting names (see below)

4. search in magpie.constants definitions

5. search in environment variables

Parameter constant_name is expected to have the format MAGPIE_[VARIABLE_NAME] although any value can be passed to retrieve generic settings from all above-mentioned search locations.

If settings_name is provided as alternative name, it is used as is to search for results if constant_name was not found. Otherwise, magpie.[variable_name] is used for additional search when the format MAGPIE_[VARIABLE_NAME] was used for constant_name (i.e.: MAGPIE_ADMIN_USER will also search for magpie.admin_user and so on for corresponding constants).

Parameters:

• constant_name – key to search for a value

• settings_container – WSGI application settings container (if not provided, uses found one in current thread)

• settings_name – alternative name for settings if specified

• default_value – default value to be returned if not found anywhere, and exception raises are disabled.

• raise_not_set – raise an exception if the found key is None, search until last case if others are None

• raise_missing – raise exception if key is not found anywhere

• print_missing – print message if key is not found anywhere, return None

• empty_missing – consider an empty value for an existing key as if it was missing (i.e.: as if not set).

Returns:

found value or default_value

Raises:

• ValueError – if resulting value is invalid based on options (by default raise missing/empty/None value)

• LookupError – if no appropriate value could be found from all search locations (according to options)

magpie.api.notifications.get_logger(name: magpie.typedefs.Str, level: int | None = None, force_stdout: bool = None, message_format: magpie.typedefs.Str | None = None, datetime_format: magpie.typedefs.Str | None = 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.

magpie.api.notifications.get_magpie_url(container: magpie.typedefs.AnySettingsContainer | None = None) → magpie.typedefs.Str

Obtains the configured Magpie URL entrypoint based on the various combinations of supported configuration settings.

See also

Documentation section Application Settings for available setting combinations.

Parameters:

container – container that provides access to application settings.

Returns:

resolved Magpie URL

magpie.api.notifications.get_settings(container: magpie.typedefs.AnySettingsContainer | None, app: bool = False) → magpie.typedefs.SettingsType

Retrieve application settings from a supported container.

Parameters:

• container – supported container with a handle to application settings.

• app – allow retrieving from current thread registry if no container was defined.

Returns:

found application settings dictionary.

Raises:

TypeError – when no application settings could be found or unsupported container.

magpie.api.notifications.raise_log(msg: magpie.typedefs.Str, exception: Type[Exception] = Exception, logger: logging.Logger | None = None, level: int = logging.ERROR) → NoReturn

Logs the provided message to the logger and raises the corresponding exception afterwards.

Raises:

exception – whichever exception provided is raised systematically after logging.

magpie.api.notifications.SMTPServerConfiguration

magpie.api.notifications.LOGGER

magpie.api.notifications.TEMPLATE_DIR

magpie.api.notifications.DEFAULT_TEMPLATE_MAPPING

magpie.api.notifications.get_email_template(template_constant: magpie.typedefs.Str, container: magpie.typedefs.AnySettingsContainer | None = None) → mako.template.Template

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

Allowed values of template_constant are:

• MAGPIE_GROUP_TERMS_APPROVED_EMAIL_TEMPLATE

• MAGPIE_GROUP_TERMS_SUBMISSION_EMAIL_TEMPLATE

• MAGPIE_USER_REGISTRATION_SUBMISSION_EMAIL_TEMPLATE

• MAGPIE_USER_REGISTRATION_APPROVAL_EMAIL_TEMPLATE

• MAGPIE_USER_REGISTRATION_APPROVED_EMAIL_TEMPLATE

• MAGPIE_USER_REGISTRATION_DECLINED_EMAIL_TEMPLATE

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

magpie.api.notifications.get_smtp_server_configuration(settings: magpie.typedefs.SettingsType) → SMTPServerConfiguration

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

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

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

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