API documentation

reportmail.command module

reportmail.command.apply_reporter(subject, template='reportmail/command_report.txt', committer=None, reporter_cls=<class 'reportmail.reporter.Reporter'>, additional_context=None)

Adding a reporting feature for django command

You can use this as decorator for Command.handle. and decorated handle() will get admin mail reporter object after self:

@apply_reporter("Title of report", 'path/to/template.txt')
def handle(self, reporter, *args, **options):
    ...

By default, apply_reporter will use the reportmail/command_report.txt template. To change the template, you can put same name template.

This decorator provide these additional values for template as context:

  • args: arguments of command calling.
  • options: option arguments of command calling and some value of enviroments.
  • command: module path for this command.

Notice that if the decorated command raises an exception, It will caught it to add the traceback to report mail. After added the error message, raised exception will be reraised.

Parameters:
  • subject – Title of report
  • template – Template to use rendering
  • committer – Committer function to be passed for the reporter.

reportmail.reporter module

A module for reporting.

Reporter(subject, template[, base_context, ...]) An object to store result messages and send messages by using committer.
console_committer(subject, body) One of committers to send messages to standard output.
admin_mail_committer(subject, body) One of committers to send messages to Admin Mails.
manager_mail_committer(subject, body) One of committers to send messages to Manager Mails.

Committers is callable to make some side-effect telling result message for administrators. Internally Reporter uses Committer to tell messages. So committers are totally separated from reporters and reporter delegates the sending processing to committers.

class reportmail.reporter.Reporter(subject, template, base_context=None, committer=None)

An object to store result messages and send messages by using committer.

The API of Reporter is quite simple. You can store messages as same way as list, like this:

>>> reporter = Reporter()
>>> reporter.append("The first line")
>>> reporter.append("The second line")
>>> reporter.commit()

When the commit() method is called, stored messages will be sent to administrators. You can also use committer as a context manager. If you do, you won’t need to call commit() method explicitly.

>>> with Reporter() as reporter:
>>>     reporter.append("The first line")
>>>     reporter.append("The second line")

This way is better and easier to read. so I recommend to use Reporter as context manager. Notice that the reporter won’t handle exceptions by default. If you want reporter to catch exceptions and report about it, write the explicit code like this:

>>> import traceback
>>> with Reporter() as reporter:
>>>     try:
>>>         # do_something()
>>>         reporter.append("Success")
>>>     except Exception as e:
>>>         reporter.append(str(e) + traceback.format_exc())
>>>         raise
Parameters:
  • subject (str) – A subject of message. This value will be deliver for committer directly.
  • template (str) – A string to specify a template to be used for build result message.
  • base_context (dict) – Base context will be provided for the template. By default, empty dict will be used.
  • committer (callable) – Committer function. By default, admin_mail_committer will be used.
abort()

Aborting commit of this reporter.

If this method is called, self.commit() will no longer send results.

refs https://github.com/hirokiky/django-reportmail/issues/7

append(text)

Storing a line of message

Parameters:text (str) – A string of message to store
commit()

A interface to send the report

Internally, this method will call self.committer by passing self.subject and result of `self.render().

extend(text_list)

Storing some lines of messages

Parameters:text (list) – A list of Some messages to store
render()

Rendering result by using stored messages

The context for template will contain messages you stored as ‘stored_text’ value. And also it contains values from base_context of constructing.

reportmail.reporter.admin_mail_committer(subject, body)

One of committers to send messages to Admin Mails.

This committer depends on django’s django.core.mail.mail_admins. So you need to set ‘ADMINS’ of the settings file. Notice that thin committer will fail silently to avoid causing unexpected error while sending admin mails.

This committer will simply use the subject as mail subject, and use body as mail body.

reportmail.reporter.console_committer(subject, body)

One of committers to send messages to standard output.

This committer will simply output the message, separating subject and body by breaking.

reportmail.reporter.manager_mail_committer(subject, body)

One of committers to send messages to Manager Mails.

This committer depends on django’s django.core.mail.mail_managers. So you need to set ‘MANAGERS’ of the settings file. Notice that thin committer will fail silently to avoid causing unexpected error while sending manager mails.

This committer will simply use the subject as mail subject, and use body as mail body.