Home | Trees | Indices | Help |
|
---|
|
TurboMail is a TurboGears extension - meaning that it starts up and shuts down alongside TurboGears applications you write in the same way that visit tracking and identity do. TurboMail uses built-in Python modules for SMTP communication and MIME e-mail creation, but greatly simplifies these tasks by performing the grunt-work for you.
Being multi-threaded, TurboMail allows you to enqueue messages to be sent and then immediately continue with processing, resulting in a much more fluid user experience. Threads are handled intelligently (increasing the number of threads as demand increases) and they are automatically recycled. There is only ever one SMTP connection per thread.
Throughput using the default options is sufficient for most use: 100 messages in 45 seconds; just over 2 messages a second. Using a greater number of threads, 10 vs. 4, 100 messages take 30 seconds; just over 3 messages a second. YMMV. Note that if a thread is idle, it will immediately deliver requests added to the queue, thus increasing the idle time will increase sparse performance.
TurboMail is heavily inspired by PHPMailer, a very, very handy class for PHP 4 & 5 by Brent R. Matzelle.
Simply easy_install the package:
easy_install TurboMail
TurboMail installs no external scripts.
Upgrading also uses easy_install:
easy_install -U TurboMail
TurboMail understands a large number of configuration options, all piggy-backed from your application's configuration. Organized into two groups, the advanced set can be safely ignored in most applications. Each option is listed with its default value.
Both a username and password are required to enable authentication.
Due to the way Python's email package handles character sets, the following additional virtual character sets are provided by TurboMail, and will override the global defaults:
Headers are not encoded. DIY.
In debug mode using a single thread with a maximum of one job can be advantageous. Having a single thread with a maximum of a single job limits TurboMail to a single SMTP connection at a time and automatically disconnects for each message.
To use TurboMail in your TurboGears application, after adding the appropriate configuration options to your application, perform the following steps:
import turbomail
message = turbomail.Message(from, to, subject)
message.plain = "Hello world!"
turbomail.enqueue(message)
Your message will now have been enqueued. It will take at most mail.interval seconds for a thread to be created to deliver it. The best case scenario is if there is an idle thread waiting, in which case delivery will be immediate.
Additionally, you can configure your application to log TurboMail events differently, in a more loggable and machine parseable way. You do so by adding the following lines to the formatters section of your log.cfg:
[[[timed_message]]] format='*(asctime)s *(message)s'
Add the following to the handlers section of log.cfg:
[[[mail_out]]] class='StreamHandler' level='INFO' args='(sys.stdout,)' formatter='timed_message'
And finally, add the following to your dev.cfg:
[[[mail]]] level='INFO' qualname='turbomail.dispatch' handlers=['mail_out'] propagate=0
If you wish to log mail dispatch to a file, for example in your production configuration, use this instead of the above:
[[handlers]] [[[mail_out]]] args="('mail.log',)" class='StreamHandler' level='INFO' formatter='timed_message' [[loggers]] [[[mail]]] level='INFO' qualname='turbomail.dispatch' handlers=['mail_out'] propagate=0
The format of turbomail.dispatch INFO log entries is:
[user@]server size ("from_name") from_addr ("to_name") to_addr - subject
Designed for easy parsing and tracking of statistics, the log format uses the following conventions:
mail.polling = True
There is, however, an outstanding bug in KIDMessage. When generating the plain-text alternative KID seems to default to ascii encoding, which bombs out if you use any extended characters in the template, or variables passed to the template.
Version: 2.1
Author: Alice Dawn Bevan-McGregor
Copyright: \xc2\xa9 2006-2007 Top Floor Computer Systems Ltd., 2007 Alice Bevan-McGregor, and contributors
License: MIT
|
|||
|
|
|||
Message Simple e-mail message class. |
|||
KIDMessage A message that accepts a named template with arguments. |
|||
MailConfigurationException There was an error in the configuration of TurboMail. |
|||
MailException The base for all TurboMail exceptions. |
|||
MailNotEnabledException Attempted to use TurboMail before being enabled. |
|
|||
|
|
|||
log = logging.getLogger("turbomail")
|
|||
_queue = None After TurboGears startup within an application which has enabled TurboMail, queue is an instance of a MailPool object. |
Home | Trees | Indices | Help |
|
---|
Generated by Epydoc 3.0.1 on Tue Jul 1 11:33:18 2008 | http://epydoc.sourceforge.net |