tgext.mailer 0.3.0

关于tgext.mailer

tgext.mailer是一个用于与事务管理器集成发送电子邮件的TurboGears2扩展。每当TurboGears提供的事务管理器提交事务时，所有电子邮件都会被发送，当事务被中止时，邮件将被丢弃。

尽管在TurboGears上还有其他用于发送电子邮件的扩展，如TurboMail，但这些扩展没有绑定到事务管理器，结构更复杂，或者不再积极维护。这导致了tgext.mailer的诞生。

tgext.mailer代码来自使用repoze.sendmail执行实际邮件投递的pyramid_mailer项目。

安装

tgext.mailer可以从PyPI安装

pip install tgext.mailer

应该对大多数用户来说都可以正常工作。

启用

要启用tgext.mailer，请将以下内容放入您的应用程序config/app_cfg.py中

import tgext.mailer
tgext.mailer.plugme(base_config)

或者您可以使用tgext.pluggable（如果可用）

from tgext.pluggable import plug
plug(base_config, 'tgext.mailer')

然后tgext.mailer将从您的应用程序配置文件中加载选项，有关可用选项的完整列表，请参阅“配置文件选项”部分。

发送电子邮件

发送电子邮件是通过邮件对象执行的，每个请求都有自己的邮件对象，该对象仅负责发送该请求的电子邮件。如果您没有将任何请求传递给get_mailer调用，则返回应用程序范围的邮件对象（不要在请求中使用它）

from tgext.mailer import get_mailer
mailer = get_mailer(request)

要发送消息，您必须首先创建一个tgext.mailer.message.Message实例

from tgext.mailer import Message

message = Message(subject="hello world",
                  sender="admin@mysite.com",
                  recipients=["john.doe@gmail.com"],
                  body="Hi John!")

然后将消息传递给Mailer实例。您可以选择立即发送消息

mailer.send(message)

或者将其添加到您的邮件队列（磁盘上的maildir）

mailer.send_to_queue(message)

如果您想在事务管理器上注册邮件之前发送电子邮件，以确保即使在事务失败的情况下也能发送，请使用

mailer.send_immediately(message)

配置文件选项

以下列出了可用的设置。将它们放置在您的配置*.ini文件中的[app:main]下。

在需要检查已发送电子邮件的测试单元中，请确保将mail.debugmailer设置为"dummy"，它将在mailer.output中保存要发送的电子邮件，而不是实际发送。

事务

如果您使用事务管理，则tgext.mailer将在事务提交时才发送电子邮件（或将它们添加到邮件队列）。

例如

import transaction

from tgext.mailer.mailer import Mailer
from tgext.mailer import Message

mailer = Mailer()
message = Message(subject="hello world",
                  sender="admin@mysite.com",
                  recipients=["john.doe@gmail.com"],
                  body="Hi John!")

mailer.send(message)
transaction.commit()

电子邮件实际上只有在事务提交后才会发送。

通常，TurboGears会在请求结束时自动提交事务，因此您不需要在发送邮件的代码中显式提交或中止。相反，如果抛出异常，事务将隐式中止且不会发送邮件；否则，将提交事务并发送邮件。

如果您使用的是应用程序范围的电子邮件管理器，则通常最好的做法是仅使用send_immediately方法，以避免在多个事务中注册相同的邮件管理器。

附件

使用tgext.mailer.message.Attachment类添加附件

from tgext.mailer import Attachment
from tgext.mailer import Message

message = Message()

photo_data = open("photo.jpg", "rb").read()
attachment = Attachment("photo.jpg", "image/jpg", photo_data)

message.attach(attachment)

您可以将数据作为字符串或文件对象传递，因此上述代码可以重写为

from tgext.mailer import Attachment
from tgext.mailer import Message

message = Message()

attachment = Attachment("photo.jpg", "image/jpg",
                        open("photo.jpg", "rb"))

message.attach(attachment)

可以通过transfer_encoding选项指定传输编码。当前支持以下选项：base64（默认）和quoted-printable。

您还可以将附件作为body和/或html参数传递，以指定Content-Transfer-Encoding或其他Attachment属性

from tgext.mailer import Attachment
from tgext.mailer import Message

body = Attachment(data="hello, arthur",
                  transfer_encoding="quoted-printable")
html = Attachment(data="<p>hello, arthur</p>",
                  transfer_encoding="quoted-printable")
message = Message(body=body, html=html)