API Reference

class mailinglogger.MailingLogger(fromaddr, toaddrs, mailhost='localhost', subject='%(line)s', send_empty_entries=False, flood_level=10, username=None, password=None, headers=None, template=None, charset='utf-8', content_type='text/plain', secure: Optional[Union[bool, SSLContext]] = None)

Bases: SMTPHandler

This is a handler for the python logging framework that sends log entries as email messages using an SMTP server.

Parameters

• fromaddr –

  The address from which email log notifications will originate.

  This must be supplied.

• toaddrs –

  A sequence of addresses to which email log notifications will be sent.

  This must be supplied.

• mailhost –

  The SMTP server that should be used to send email notifications.

  This can either be a string containing the hostname of the SMTP server or a tuple containing the hostname and port number of the SMTP server. If only the hostname is specified, it is assumed that the SMTP server is listening on port 25.

  default: ('localhost', 25)

• username –

  The username to use for SMTP authentication.

  If both username and password are supplied then SMTP login will be performed before any email is sent. Otherwise, no SMTP authentication will be performed. For performance reasons, it’s recommended that you don’t use SMTP authentication unless you absolutely need to.

• password –

  The password to use for SMTP authentication.

  If both username and password are supplied then SMTP login will be performed before any email is sent. Otherwise, no SMTP authentication will be performed. For performance reasons, it’s recommended that you don’t use SMTP authentication unless you absolutely need to.

• subject –

  This is a format string specifying what information will be included in the subject line of the email notification.

  Information on what can be included in a subject format string can be found in the SubjectFormatter documentation.

  default: '%(line)s'

• send_empty_entries –

  This is a boolean parameter which specifies whether empty log entries will be mailed or not.

  default: False

• flood_level –

  This is an integer parameter specifying the maximum number of emails that can be sent in an hour that will not be considered a “flood”.

  When a “flood” is detected, one email is sent at the CRITICAL level indicating that a flood has been detected, and no more emails will be sent in the same hour.

  So, this option, in effect, specifies the maximum number of emails that will be sent in any particular hour of the day.

  default: 10

• headers –

  This is a dictionary containing headers and their values to be added to any emails sent.

  default: {}

• template –

  A string template to use to wrap the body of emails sent. Should contain exactly one %s.

  default: None

• charset –

  The charset passed to MIMEText when the message logged is a unicode instance.

  default: utf-8

  Note

  This parameter is only used when a unicode object is logged. The default will amost always suffice, do not pass this parameter unless you really need to.

• content_type –

  The content type to use when setting the Content-Type header on any email sent. Only content types of text/ are supported.

  default: text/plain

• secure –

  If TLS is required, this must be True or an ssl.SSLContext object which will be passed to smtplib.SMTP.starttls().

  Note

  If TLS is required, both username and password must also be provided.

  default: None

class mailinglogger.SummarisingLogger(fromaddr, toaddrs, mailhost='localhost', subject='Summary of Log Messages (%(levelname)s)', send_empty_entries=True, atexit=True, username=None, password=None, headers=None, send_level=None, template=None, charset='utf-8', content_type='text/plain', secure: Optional[Union[bool, SSLContext]] = None, flood_level=100)

Bases: FileHandler

SummarisingLogger is a handler for the python logging framework that accumulates logged entries and sends a single email containing them all using an SMTP server when close() called.

Parameters

• fromaddr –

  The address from which the summary email will originate.

  This must be supplied.

• toaddrs –

  A sequence on strings containing addresses to which the summary email will be sent.

  This must be supplied.

• mailhost –

  The SMTP server that should be used to send the summary mail.

  This can either be a string containing the hostname of the SMTP server or a tuple containing the hostname and port number of the SMTP server. If only the hostname is specified, it is assumed that the SMTP server is listening on port 25.

  default: ('localhost', 25)

• username –

  The username to use for SMTP authentication.

  If both username and password are supplied then SMTP login will be performed before any email is sent. Otherwise, no SMTP authentication will be performed. For performance reasons, it’s recommended that you don’t use SMTP authentication unless you absolutely need to.

• password –

  The password to use for SMTP authentication.

  If both username and password are supplied then SMTP login will be performed before any email is sent. Otherwise, no SMTP authentication will be performed. For performance reasons, it’s recommended that you don’t use SMTP authentication unless you absolutely need to.

• subject –

  This is a format string specifying what information will be included in the subject line of the summary email.

  Information on what can be included in a subject format string can be found in the SubjectFormatter documentation.

  Note

  %(levelname)s when used in the subject parameter will be the highest level message handled by the SummarisingLogger.

  default: 'Summary of Log Messages (%(levelname)s)'

• send_empty_entries –

  This is a boolean parameter which specifies whether a summary message will be sent even if no messages have been logged.

  default: True

• atexit –

  If True, the close() method of the summarising logger is set as an atexit function that runs when the currently executing python script finishes.

  default: True

• headers –

  This is a dictionary containing headers and their values to be added to any emails sent.

  default: {}

• send_level –

  If supplied, the summary email will not be sent unless a message has been logged that is at or above the level specified.

  If not supplied, the summary email will be sent if a message has been logged at or above the level set on the handler.

  default: None

• template –

  A string template to use to wrap the body of the summary email. Should contain exactly one %s.

  default: None

• charset –

  This string value has two uses.

  Firstly, it is used to encode the messages logged to the summary and then decode the whole summary back to unicode when the summary is sent.

  Secondlly, if that unicode message cannot be encoded as ascii, it is passed to the MIMEText used to produce the summary email.

  default: utf-8

  Note

  This default will amost always suffice, do not pass this parameter unless you really need to.

• content_type –

  The content type to use when setting the Content-Type header on any email sent. Only content types of text/ are supported.

  default: text/plain

• secure –

  If TLS is required, this must be True or an ssl.SSLContext object which will be passed to smtplib.SMTP.starttls().

  Note

  If TLS is required, both username and password must also be provided.

  default: None

• flood_level –

  The maximum number of messages that can be logged before flood protection begins. Flood protection prevents overly large emails being sent by excluding exccess messages. When this occurs, a CRITICAL level message will be included detailing the number of messages excluded. The last 5 messages logged before the email is sent will always be included.

  default: 100

open()

This method creates the temporary file used by SummarisingLogger to accumulate logged messages and enables it for processing of log messages.

close()

This method closes the temporary file used by SummarisingLogger to accumulate logged messages and sends any logged messages in a single email.

It also disables the SummarisingLogger’s processing of log messages.

reopen()

This is shorthand for calling close() followed by open().

class mailinglogger.common.SubjectFormatter(fmt=None, datefmt=None)

Bases: Formatter

This is a logging formatter tailored to formatting log messages to appear in the subject line of an email. For details of how these differ from normal Formatter objects, see the SubjectFormatter documentation.

Note

You should not need to manually instantiate this class as this will be done by either MailingLogger or SummarisingLogger when the subject parameter to their constructors is processed.

class mailinglogger.common.HTMLFilter

This is a logging filter that quotes logged messages such that they are safe for use in HTML emails. For an example usage, see Sending HTML Emails.