`wuttjamaican.email`¶

Email Handler

class wuttjamaican.email.EmailHandler(*args, **kwargs)[source]¶

Base class and default implementation for the email handler.

Responsible for sending email messages on behalf of the app.

You normally would not create this directly, but instead call get_email_handler() on your app handler.

deliver_message(message, sender=None, recips=None)[source]¶

Deliver a message via SMTP smarthost.

Parameters:

message – Either a Message object or similar, or a string representing the complete message to be sent as-is.
sender – Optional sender address to use for delivery. If not specified, will be read from message.
recips – Optional recipient address(es) for delivery. If not specified, will be read from message.

A general rule here is that you can either provide a proper Message object, or you must provide sender and recips. The logic is not smart enough (yet?) to parse sender/recips from a simple string message.

Note also, this method does not (yet?) have robust error handling, so if an error occurs with the SMTP session, it will simply raise to caller.

Returns:: None

get_auto_bcc(key)[source]¶: Returns automatic bcc recipient address(es) for a message, as determined by config.

get_auto_cc(key)[source]¶: Returns automatic cc recipient address(es) for a message, as determined by config.

get_auto_html_body(key, context=None, fallback_key=None)[source]¶: Returns automatic html_body content for a message, as determined by config. This renders a template with the given context.

get_auto_replyto(key)[source]¶: Returns automatic replyto address for a message, as determined by config.

get_auto_sender(key)[source]¶: Returns automatic sender address for a message, as determined by config.

get_auto_subject(key, context=None, rendered=True, default=None, fallback_key=None, setting=None, prefix=True, default_prefix=None)[source]¶

Returns automatic subject line for a message, as determined by config.

This calls get_auto_subject_template() and then (usually) renders the result using the given context, and adds the get_auto_subject_prefix().

Parameters:

key – Key for the email type. See also the fallback_key param, below.
context – Dict of context for rendering the subject template, if applicable.
rendered – If this is False, the “raw” subject template will be returned, instead of the final/rendered subject text.
default – Default subject to use if none is configured.
fallback_key – Optional fallback email key to use for config lookup, if nothing is found for key.
setting – Optional EmailSetting class or instance. This is passed along to get_auto_subject_template().
prefix – Boolean indicating the message subject should be auto-prefixed. This is ignored when rendered param is false.
default_prefix – Default subject prefix to use if none is configured.

Returns:

Final subject text, either “raw” or rendered.

get_auto_subject_prefix(key, default=None, fallback_key=None, setting=None)[source]¶

Returns the string to use for automatic subject prefix, as determined by config. This is called by get_auto_subject().

Note that unlike the subject proper, the prefix is just a normal string, not a template.

Example prefix is "[Wutta]" - trailing space will be added automatically when applying the prefix to a message subject.

Parameters:

key – The email key requested.
default – Default prefix to use if none is configured.
fallback_key – Optional fallback email key to use for config lookup, if nothing is found for key.
setting – Optional EmailSetting class or instance. This may be used to determine the “default” prefix if none is configured. You can specify this as an optimization; otherwise it will be fetched if needed via get_email_setting().

Returns:

Final subject prefix string

get_auto_subject_template(key, default=None, fallback_key=None, setting=None)[source]¶

Returns the template string to use for automatic subject line of a message, as determined by config.

In many cases this will be a simple string and not a “template” per se; however it is still treated as a template.

The template returned from this method is used to render the final subject line in get_auto_subject().

Parameters:

key – Key for the email type.
default – Default subject to use if none is configured.
fallback_key – Optional fallback email key to use for config lookup, if nothing is found for key.
setting – Optional EmailSetting class or instance. This may be used to determine the “default” subject if none is configured. You can specify this as an optimization; otherwise it will be fetched if needed via get_email_setting().

Returns:

Final subject template, as raw text.

get_auto_to(key)[source]¶: Returns automatic to recipient address(es) for a message, as determined by config.

get_auto_txt_body(key, context=None, fallback_key=None)[source]¶: Returns automatic txt_body content for a message, as determined by config. This renders a template with the given context.

get_email_context(key, context=None)[source]¶

This must return the “full” context for rendering the email subject and/or body templates.

Normally the input context is coming from the send_email() param of the same name.

By default, this method modifies the input context to add the following:

config - reference to the config object
app - reference to the app handler

Subclass may further modify as needed.

Parameters:

key – The email key for which to get context.
context – Input context dict.

Returns:

Final context dict

get_email_modules()[source]¶

Returns a list of all known email modules.

This will discover all email modules exposed by the app, and/or its providers.

Calls get_provider_modules() under the hood, for email module type.

get_email_setting(key, instance=True)[source]¶

Retrieve the email setting for the given email key (if it exists).

Parameters:

key – Key for the email type.
instance – Whether to return the class, or an instance.

Returns:

EmailSetting class or instance, or None if the setting could not be found.

get_email_settings()[source]¶

Returns a dict of all known email settings, keyed by email key.

This calls get_email_modules() and for each module, it discovers all the email settings it contains.

get_notes(key)[source]¶

Returns configured “notes” for the given email key.

Parameters:: key – Key for the email type.
Returns:: Notes as string if found; otherwise None.

is_enabled(key)[source]¶

Returns flag indicating whether the given email type is “enabled” - i.e. whether it should ever be sent out (enabled) or always suppressed (disabled).

All email types are enabled by default, unless config says otherwise; e.g. to disable foo emails:

[wutta.email]

# nb. this is fallback if specific type is not configured
default.enabled = true

# this disables 'foo' but e.g 'bar' is still enabled per default above
foo.enabled = false

In a development setup you may want a reverse example, where all emails are disabled by default but you can turn on just one type for testing:

[wutta.email]

# do not send any emails unless explicitly enabled
default.enabled = false

# turn on 'bar' for testing
bar.enabled = true

See also sending_is_enabled() which is more of a master shutoff switch.

Parameters:: key – Unique identifier for the email type.
Returns:: True if this email type is enabled, otherwise false.

make_auto_message(key, context=None, default_subject=None, prefix_subject=True, default_prefix=None, fallback_key=None, **kwargs)[source]¶

Make a new email message using config to determine its properties, and auto-generating body from a template.

Once everything has been collected/prepared, make_message() is called to create the final message, and that is returned.

Parameters:

key – Unique key for this particular “type” of message. This key is used as a prefix for all config settings and template names pertinent to the message. See also the fallback_key param, below.
context – Context dict used to render template(s) for the message.
default_subject – Optional subject template/string to use, if config does not specify one.
prefix_subject – Boolean indicating the message subject should be auto-prefixed.
default_prefix – Default subject prefix to use if none is configured.
fallback_key – Optional fallback email key to use for config/template lookup, if nothing is found for key.
**kwargs – Any remaining kwargs are passed as-is to make_message(). More on this below.

Returns:

Message object.

This method may invoke some others, to gather the message attributes. Each will check config, or render a template, or both. However if a particular attribute is provided by the caller, the corresponding “auto” method is skipped.

get_auto_sender()
get_auto_subject()
get_auto_to()
get_auto_cc()
get_auto_bcc()
get_auto_txt_body()
get_auto_html_body()

make_message(**kwargs)[source]¶

Make and return a new email message.

This is the “raw” factory which is simply a wrapper around the class constructor. See also make_auto_message().

Returns:: Message object.

send_email(key=None, context=None, message=None, sender=None, recips=None, fallback_key=None, **kwargs)[source]¶

Send an email message.

This method can send a message you provide, or it can construct one automatically from key / config / templates.

The most common use case is assumed to be the latter, where caller does not provide the message proper, but specifies key and context so the message is auto-created. In that case this method will also check is_enabled() and skip the sending if that returns false.

Parameters:

key – When auto-creating a message, this is the email key identifying the type of email to send. Used to lookup config settings and template files. See also the fallback_key param, below.
context – Context dict for rendering automatic email template(s).
message – Optional pre-built message instance, to send as-is. If specified, nothing about the message will be auto-assigned from config.
sender –
Optional sender address for the message/delivery.

If message is not provided, then the sender (if provided) will also be used when constructing the auto-message (i.e. to set the From: header).

In any case if sender is provided, it will be used for the actual SMTP delivery.
recips –
Optional list of recipient addresses for delivery. If not specified, will be read from the message itself (after auto-generating it, if applicable).
Note

This param does not affect an auto-generated message; it is used for delivery only. As such it must contain all true recipients.

If you provide the message but not the recips, the latter will be read from message headers: To:, Cc: and Bcc:

If you want an auto-generated message but also want to override various recipient headers, then you must provide those explicitly:
```
context = {'data': [1, 2, 3]}
app.send_email('foo', context, to='me@example.com', cc='bobby@example.com')
```
fallback_key – Optional fallback email key to use for config/template lookup, if nothing is found for key.
**kwargs – Any remaining kwargs are passed along to make_auto_message(). So, not used if you provide the message.

sending_is_enabled()[source]¶

Returns boolean indicating if email sending is enabled.

Set this flag in config like this:

[wutta.mail]
send_emails = true

Note that it is OFF by default.

class wuttjamaican.email.EmailSetting(config)[source]¶

Base class for all email settings.

Each email type which needs to have settings exposed e.g. for editing, should define a subclass within the appropriate email module.

The name of each subclass should match the email key which it represents. For instance:

from wuttjamaican.email import EmailSetting

class poser_alert_foo(EmailSetting):
    """
    Sent when something happens that we think deserves an alert.
    """

    default_subject = "Something happened!"

    # nb. this is not used for sending; only preview
    def sample_data(self):
        return {
            'foo': 1234,
            'msg': "Something happened, thought you should know.",
        }

# (and elsewhere..)
app.send_email('poser_alert_foo', {
    'foo': 5678,
    'msg': "Can't take much more, she's gonna blow!",
})

Defining a subclass for each email type can be a bit tedious, so why do it? In fact there is no need, if you just want to send emails.

The purpose of defining a subclass for each email type is 2-fold, but really the answer is “for maintenance sake” -

gives the app a way to discover all emails, so settings for each can be exposed for editing
allows for hard-coded sample context which can be used to render templates for preview

key¶

Unique identifier for this email type.

This is the email key used for config/template lookup, e.g. when sending an email.

This is automatically set based on the class name so there is no need (or point) to set it. But the attribute is here for read access, for convenience / code readability:

class poser_alert_foo(EmailSetting):
   default_subject = "Something happened!"

handler = app.get_email_handler()
setting = handler.get_email_setting("poser_alert_foo")
assert setting.key == "poser_alert_foo"

wuttjamaican.email¶

`wuttjamaican.email`¶