Email Modules

hedwig.email.format

class hedwig.email.format.UnwrapFileSystemLoader(searchpath: str | PathLike[str] | Sequence[str | PathLike[str]], encoding: str = 'utf-8', followlinks: bool = False)

Template loader which unwraps lines as the template is read.

Email templates are stored in text files where long lines are typically wrapped at a suitable width using single line breaks. This class unwraps the template by removing such breaks. This allows single line breaks in text substituted into templates to be retained. Unwrapping after rendering the template would remove both (unwanted) line breaks from the template file and (presumably intentional) line breaks in substituted text.

Also recognizes a special comment template comment {# BR #} to indicate where a single line break should be retained. (This must appear on a line by itself.)

get_source(environment, template)

Get the template source, filename and reload helper for a template. It’s passed the environment and template name and has to return a tuple in the form (source, filename, uptodate) or raise a TemplateNotFound error if it can’t locate the template.

The source part of the returned tuple must be the source of the template as a string. The filename should be the name of the file on the filesystem if it was loaded from there, otherwise None. The filename is used by Python for the tracebacks if no loader extension is used.

The last item in the tuple is the uptodate function. If auto reloading is enabled it’s always called to check if the template changed. No arguments are passed so the function must store the old state somewhere (for example in a closure). If it returns False the template will be reloaded.

hedwig.email.format._unwrap_email_template(source)

Helper function for UnwrapFileSystemLoader.

Attempts to unwrap the lines of an email template. Performs some basic processing:

  • Recognizes the break comment {# BR #}.

  • Assumes lines containing only a single {% … %} statement do not generate output and so does not add a space before the next line. Records such status before if-elif-else-endif structures to restore it for each branch (but does not accumulate status from the branches, assuming them all to be similar).

hedwig.email.format.get_environment()

Get Jinja environment for processing email templates.

If an environment has already been constructed, it is stored in the environment global variable and will be returned. Otherwise a new environment is prepared. The environment configuration has:

  • The data/home directory (within the Hedwig home directory) configured as the template loading path.

  • Template globals:
    • From the application section of the configuration file:

      • application_name

    • From the email section of the configuration file:

      • email_footer_title

      • email_footer_url

      • email_footer_email

  • Filters:

    • format_datetime

hedwig.email.format.render_email_template(name, context, facility=None)

Render a template and then adjust paragraph breaks.

If a facility (view class) is given then the template will be loaded from a directory of the facility’s code, if it exists, otherwise from the generic directory. The template context will also be extended to include:

  • facility_name

  • facility_definite_name

Note

This function no longer line-wraps the email message (using wrap_email_text()) and instead returns plain text suitable for use with MessageFormatType.PLAIN. If other formats are to be used, it may be necessary to alter the return value of this function to include the format type.

hedwig.email.format._tidy_email_text(text)

Tidy the spacing of email text generated from a template.

  • Ensures only one blank line between paragraphs.

  • Merges multiple consecutive spaces into one except at the start of a line.

hedwig.email.format.wrap_email_text(text)

Line-wraps email message text.

  • The message is broken into paragraphs, at multiple line breaks.

  • Each line in the paragraph is then line-wrapped.

  • A trailing space is added to each wrapped line, except the last (flowed email format).

  • The lines of the email are rejoined, with a blank line between paragraphs.

Note

The behavior of this function has changed to preserve single line breaks by individually wrapping each line within each paragraph.

hedwig.email.format._get_text_wrapper()

Get TextWrapper object.

hedwig.email.format.unwrap_email_text(text)

Unwrap email text, from the style of “format=flowed” to paragraphs on single lines.

This is the inverse of wrap_email_text() and can be used when email text (which has be prepared for sending with format=flowed) is to be sent in a different style, such as “quoted-printable” content encoding.

hedwig.email.poll

hedwig.email.poll.send_queued_messages(db, dry_run=False)

Attempts to send any unsent email messages.

Queries the database for an unsent message. If messages is found, they are sent and then marked as sent in the database.

Returns the number of messages sent.

hedwig.email.send

hedwig.email.send._prepare_email_message_bytes(*args, **kwargs)
hedwig.email.send.quitting(smtp)

Context manager which calls the quit method on the given object at the end of the block.

This function is analogous to the standard contextlib.closing function.

hedwig.email.send.send_email_message(message, dry_run=False)

Send an email message.

On success, returns the message identifier.

hedwig.email.send._prepare_email_message(message, from_, identifier=None, maxheaderlen=None)

Prepare an email message.

This is a separate function to allow this routine to be tested independently of actual message sending.

hedwig.email.send._prepare_email_message_py3(message, from_, recipients, extra_headers, maxheaderlen)

Generate email message using the “new” EmailMessage API.

hedwig.email.send._prepare_email_message_py2(message, from_, recipients, extra_headers, maxheaderlen)

Generate email message using the email.mime package found in Python 2.

hedwig.email.send._prepare_email_message_body(message)
hedwig.email.send._prepare_address_header(names_addresses)

Encode an email address header (‘From’ or ‘To’) with the given names and addresses. The addresses must be ASCII and will be enclosed in angle brackets. The names will be enclosed in double quotes if ASCII or encoded as quoted printable otherwise.

hedwig.email.util

hedwig.email.util.is_valid_email(address)