magpie.api.notifications ======================== .. py:module:: magpie.api.notifications Attributes ---------- .. autoapisummary:: magpie.api.notifications.SMTPServerConfiguration magpie.api.notifications.LOGGER magpie.api.notifications.TEMPLATE_DIR magpie.api.notifications.DEFAULT_TEMPLATE_MAPPING Functions --------- .. autoapisummary:: magpie.api.notifications.get_constant magpie.api.notifications.get_logger magpie.api.notifications.get_magpie_url magpie.api.notifications.get_settings magpie.api.notifications.raise_log magpie.api.notifications.get_email_template magpie.api.notifications.get_smtp_server_configuration magpie.api.notifications.get_smtp_server_connection magpie.api.notifications.make_email_contents magpie.api.notifications.send_email Module Contents --------------- .. py:function:: get_constant(constant_name: magpie.typedefs.Str, settings_container: Optional[magpie.typedefs.AnySettingsContainer] = None, settings_name: Optional[magpie.typedefs.Str] = None, default_value: Optional[magpie.typedefs.SettingValue] = 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 :paramref:`constant_name`: 1. search in :py:data:`MAGPIE_CONSTANTS` 2. search in settings if specified 3. search alternative setting names (see below) 4. search in :mod:`magpie.constants` definitions 5. search in environment variables Parameter :paramref:`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 :paramref:`settings_name` is provided as alternative name, it is used as is to search for results if :paramref:`constant_name` was not found. Otherwise, ``magpie.[variable_name]`` is used for additional search when the format ``MAGPIE_[VARIABLE_NAME]`` was used for :paramref:`constant_name` (i.e.: ``MAGPIE_ADMIN_USER`` will also search for ``magpie.admin_user`` and so on for corresponding constants). :param constant_name: key to search for a value :param settings_container: WSGI application settings container (if not provided, uses found one in current thread) :param settings_name: alternative name for `settings` if specified :param default_value: default value to be returned if not found anywhere, and exception raises are disabled. :param raise_not_set: raise an exception if the found key is ``None``, search until last case if others are ``None`` :param raise_missing: raise exception if key is not found anywhere :param print_missing: print message if key is not found anywhere, return ``None`` :param 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) :raises LookupError: if no appropriate value could be found from all search locations (according to options) .. 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_magpie_url(container: Optional[magpie.typedefs.AnySettingsContainer] = None) -> magpie.typedefs.Str Obtains the configured Magpie URL entrypoint based on the various combinations of supported configuration settings. .. seealso:: Documentation section :ref:`config_app_settings` for available setting combinations. :param container: container that provides access to application settings. :return: resolved Magpie URL .. py:function:: get_settings(container: Optional[magpie.typedefs.AnySettingsContainer], app: bool = False) -> magpie.typedefs.SettingsType Retrieve application settings from a supported container. :param container: supported container with a handle to application settings. :param app: allow retrieving from current thread registry if no container was defined. :return: found application settings dictionary. :raise TypeError: when no application settings could be found or unsupported container. .. py:function:: raise_log(msg: magpie.typedefs.Str, exception: Type[Exception] = Exception, logger: Optional[logging.Logger] = 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. .. py:data:: SMTPServerConfiguration .. py:data:: LOGGER .. py:data:: TEMPLATE_DIR .. 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:: 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. .. py:function:: get_smtp_server_connection(config: SMTPServerConfiguration) -> Union[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. .. py:function:: make_email_contents(config: SMTPServerConfiguration, settings: magpie.typedefs.SettingsType, template: mako.template.Template, parameters: Optional[TemplateParameters] = None) -> magpie.typedefs.Str Generates the email contents using the template, substitution parameters, and the target email server configuration. .. 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).