[Zope3-checkins] CVS: Zope3/src/zope/app/interfaces - mail.py:1.4
Albertas Agejevas
alga@codeworks.lt
Mon, 23 Jun 2003 11:46:09 -0400
Update of /cvs-repository/Zope3/src/zope/app/interfaces
In directory cvs.zope.org:/tmp/cvs-serv32331/src/zope/app/interfaces
Modified Files:
mail.py
Log Message:
Transactionaly safe QueuedMailService merged into head.
If you want to play with it, uncomment the example tag in
zope/app/mail/configure.zcml .
=== Zope3/src/zope/app/interfaces/mail.py 1.3 => 1.4 ===
--- Zope3/src/zope/app/interfaces/mail.py:1.3 Wed May 21 06:52:53 2003
+++ Zope3/src/zope/app/interfaces/mail.py Mon Jun 23 11:45:39 2003
@@ -11,9 +11,47 @@
# FOR A PARTICULAR PURPOSE.
#
##############################################################################
-"""MailService Interfaces
+"""Mail service interfaces
-Interfaces relevant for the MailService
+Email sending from Zope 3 applications works as follows:
+
+- A Zope 3 application locates a mail service (IMailService) and feeds a
+ message to it. It gets back a unique message ID so it can keep track of the
+ message by subscribing to IMailEvent events.
+
+- The mail service registers with the transaction system to make sure the
+ message is only sent when the transaction commits successfully. (Among
+ other things this avoids duplicate messages on ConflictErrors.)
+
+- If the mail service is a IQueuedMailService, it puts the message into a
+ queue (a Maildir mailbox in the file system). A separate process or thread
+ (IMailQueueProcessor) watches the queue and delivers messages
+ asynchronously. Since the queue is located in the file system, it survives
+ Zope restarts or crashes and the mail is not lost. The queue processor
+ can implement batching to keep the server load low.
+
+- If the mail service is a IDirectMailService, it delivers messages
+ synchronously during the transaction commit. This is not a very good idea,
+ as it makes the user wait. Note that transaction commits must not fail,
+ but that is not a problem, because mail delivery problems dispatch an
+ event instead of raising an exception.
+
+ XXX and there's the problem -- sending events causes unknown code to be
+ executed during the transaction commit phase. There should be a way to
+ start a new transaction for event processing after this one is commited.
+
+- An IMailQueueProcessor or IDirectMailService actually delivers the messages
+ by using a mailer (IMailer) component that encapsulates the delivery
+ process. There are currently two mailers:
+
+ - ISMTPMailer sends all messages to a relay host using SMTP
+
+ - ISendmailMailer sends messages by calling an external process (usually
+ /usr/lib/sendmail on Unix systems).
+
+- If mail delivery succeeds, an IMailSentEvent is dispatched by the mailer.
+ If mail delivery fails, no exceptions are raised, but an IMailErrorEvent is
+ dispatched by the mailer.
$Id$
"""
@@ -26,118 +64,138 @@
class IMailService(Interface):
- """A mail service allows someone to send an email to a group of people.
+ """A mail service allows someone to send an email to a group of people."""
- Note: This interface is purposefully held very simple, so that it is easy
- to provide a basic mail service implementation.
- """
+ def send(fromaddr, toaddrs, message):
+ """Sends an email message.
- hostname = zope.schema.TextLine(
- title=_(u"Hostname"),
- description=_(u"Name of server to be used as SMTP server."))
+ 'fromaddr' is the sender address (byte string),
- port = zope.schema.Int(
- title=_(u"Port"),
- description=_(u"Port of SMTP service"),
- default=25)
+ 'toaddrs' is a sequence of recipient addresses (byte strings).
- username = zope.schema.TextLine(
- title=_(u"Username"),
- description=_(u"Username used for optional SMTP authentication."))
+ 'message' is a byte string that contains both headers and body
+ formatted according to RFC 2822. If it does not contain a Message-Id
+ header, it will be generated and added automatically.
- password = zope.schema.Password(
- title=_(u"Password"),
- description=_(u"Password used for optional SMTP authentication."))
+ Returns the message ID.
- def send(fromaddr, toaddrs, message):
- """Send a message to the tos (list of email unicode strings) with a
- sender specified in from (unicode string).
+ You can subscribe to IMailEvent events for notification about problems
+ or successful delivery.
+
+ Messages are actually sent during transaction commit.
"""
-# XXX: Needs better name: AsyncMailService, MailerMailService, ...
-class IAsyncMailService(IMailService):
- """This mail service handles mail delivery using so called Mailer objects.
+class IDirectMailService(IMailService):
+ """A mail service that delivers messages synchronously during transaction
+ commit.
- The policies for sending the mail are encoded in the Mailer object. Also,
- it is recommended that the mailer is called in a different thread, so that
- the request is not blocked.
+ Not useful for production use, but simpler to set up and use.
"""
- def createMailer(name):
- """Create a Mailer object which class was registered under the passed
- name."""
-
- def getMailerNames():
- """Return a list of the names of all registered mailers."""
-
- def getDefaultMailerName():
- """Return the name of the default Mailer. None, means there is no
- default mailer class defined.
- """
-
- def send(fromaddr, toaddrs, message, mailer=None):
- """This interface extends the send method by an optional mailer
- attribute. If the mailer is None, an object from the default mailer
- class is created and used.
- """
+ mailer = Attribute("IMailer that is used for message delivery")
-class IMailer(Interface):
- """This is a generic Mailer interface.
+class IQueuedMailService(IMailService):
+ """A mail service that puts all messages into a queue in the filesystem.
- Mailers implement mailing policies, such as batching, scheduling and so
- on.
+ Messages will be delivered asynchronously by a separate component.
"""
- def send(fromaddr, toaddrs, message, hostname, port, username, password):
- """Send a message. How and when the mailer is going to send
- out the mail is purely up to the mailer's policy.
- """
+ queuePath = zope.schema.TextLine(
+ title=_(u"Queue path"),
+ description=_(u"Pathname of the directory used to queue mail."))
-class IBatchMailer(IMailer):
- """The Batch Mailer allows for sending emails in batches, so that the
- server load will not be too high.
+class IMailQueueProcessor(Interface):
+ """A mail queue processor that delivers queueud messages asynchronously.
"""
- batchSize = zope.schema.Int(
- title=_(u"Batch Size"),
- description=_(u"Amount of E-mails sent in one batch."),
- min=1)
-
- batchDelay = zope.schema.Int(
- title=_(u"Batch Delay"),
- description=_(u"Delay time in milliseconds between batches."),
- min=100)
+ queuePath = zope.schema.TextLine(
+ title=_(u"Queue Path"),
+ description=_(u"Pathname of the directory used to queue mail."))
+
+ pollingInterval = zope.schema.Int(
+ title=_(u"Polling Interval"),
+ description=_(u"How often the queue is checked for new messages"
+ " (in milliseconds)"),
+ default=5000)
+ mailer = Attribute("IMailer that is used for message delivery")
-class IScheduleMailer(IMailer):
- """This mailer allows you to specify a specific date/time to send the
- mails.
- """
- sendAt = zope.schema.Datetime(
- title=_(u"Send at"),
- description=_(u"Date/time the message should be send."))
+class IMailer(Interface):
+ """Mailer handles syncrhonous mail delivery."""
+
+ def send(fromaddr, toaddrs, message):
+ """Sends an email message.
+
+ 'fromaddr' is the sender address (unicode string),
+
+ 'toaddrs' is a sequence of recipient addresses (unicode strings).
+
+ 'message' contains both headers and body formatted according to RFC
+ 2822. It should contain at least Date, From, To, and Message-Id
+ headers.
+
+ Messages are sent immediatelly.
+
+ Dispatches an IMailSentEvent on successful delivery, otherwise an
+ IMailErrorEvent.
+ """
+
+
+class ISMTPMailer(IMailer):
+ """A mailer that delivers mail to a relay host via SMTP."""
+
+ hostname = zope.schema.TextLine(
+ title=_(u"Hostname"),
+ description=_(u"Name of server to be used as SMTP server."))
+
+ port = zope.schema.Int(
+ title=_(u"Port"),
+ description=_(u"Port of SMTP service"),
+ default=25)
+
+ username = zope.schema.TextLine(
+ title=_(u"Username"),
+ description=_(u"Username used for optional SMTP authentication."))
+
+ password = zope.schema.Password(
+ title=_(u"Password"),
+ description=_(u"Password used for optional SMTP authentication."))
+
+
+class ISendmailMailer(IMailer):
+ """A mailer that delivers mail by calling an external process."""
+
+ command = zope.schema.BytesLine(
+ title=_(u"Command"),
+ description=_(u"Command used to send email."),
+ default="/usr/lib/sendmail -oem -oi -f %(from)s %(to)s")
class IMailEvent(IEvent):
- """Generic Mailer event that can be sent from the mailer or the mail
- service.
- """
+ """Generic mail event."""
- mailer = Attribute("Mailer object that is used to send the mail.")
+ messageId = Attribute("Message id according to RFC 2822")
class IMailSentEvent(IMailEvent):
- """Event that is fired when all the mail in the mailer was sent.
+ """Event that is fired when a message is succesfully sent.
- Note: Subscribing to this event eliminates the need for implementing
- callback functions for the asynchronous delivery.
+ This does not mean that all the recipients have received it, it only
+ means that the message left this system successfully. It is possible
+ that a bounce message will arrive later from some remote mail server.
"""
+class IMailErrorEvent(IMailEvent):
+ """Event that is fired when a message cannot be delivered."""
+
+ errorMessage = Attribute("Error message")
+
+
class IMaildirFactory(Interface):
@@ -211,4 +269,3 @@
Calling abort() more than once is allowed.
"""
-