aiosmtpd 1.4.2

介绍

概念

命令行用法

编程方式用法

SMTP 模块

LMTP 类

处理程序

• 处理程序挂钩
  • Common Arguments
  • Supported Hooks
• 内置处理程序
• 邮箱处理程序

身份验证系统

PROXY 协议支持

从 smtpd 迁移到 aiosmtpd

测试

aiosmtpd

aiosmtpd 新闻

1. 首页
2. aiosmtpd 1.4.2
3. 处理程序

处理程序 ¶

Handlers are classes which can implement hook methods that get called at various points in the SMTP dialog.

Handlers can also be named on the 命令行 , but if the class’s constructor takes arguments, you must define a @classmethod that converts the positional arguments and returns a handler instance:

classmethod from_cli ( cls , parser , * args ) ¶

Convert the positional arguments, as strings passed in on the command line, into a handler instance.

parser 是 ArgumentParser instance in use.

If this method does not recognize the positional arguments passed in parser , it can optionally call parser.error with the error message.

若 from_cli() is not defined, the handler can still be used on the command line, but its constructor cannot accept arguments.

处理程序挂钩 ¶

Handlers can implement hooks that get called during the SMTP dialog, or in exceptional cases. These handler hooks are ALL called asynchronously (i.e. they are coroutines).

All handler hooks are optional and default behaviors are carried out by the SMTP class when a hook is omitted, so you only need to implement the ones you care about.

When a handler hook is defined, it may have additional responsibilities as described below.

Common Arguments ¶

All handler hooks will be called with at least three arguments:

server : SMTP ¶

SMTP server instance

session : Session ¶

session instance currently being handled, and

envelope : Envelope ¶

envelope instance of the current SMTP Transaction

Some handler hooks will receive additional arguments.

Supported Hooks ¶

The following hooks are currently supported (in alphabetical order):

handle_AUTH ( server , session , envelope , args )

Called to handle AUTH command if you need custom AUTH behavior.

For more information, please read the documentation for 身份验证系统 .

async handle_DATA ( server , session , envelope ) → str ¶

返回

Response message to be sent to the client

Called during DATA after the entire message ( “SMTP content” as described in RFC 5321) has been received.

The content is available in envelope.original_content as type bytes , normalized according to the transparency rules as defined in RFC 5321, §4.5.2 .

此外， envelope.content attribute will also contain the contents; the type depends on whether SMTP was instantiated with decode_data=False or decode_data=True 。见 Envelope.content for more info.

async handle_EHLO ( server , session , envelope , hostname , responses ) → List [ str ]

参数

hostname ( str ) – The host name given by the client in the EHLO 命令

返回

Response message to be sent to the client

This hook is called during EHLO .

This hook may push additional 250-<command> responses to the client by doing await server.push(status) before returning "250 HELP" as the final response.

重要

If the handler sets the session.host_name attribute to a false-y value (or leave it as the default None value) it will signal later steps that HELO failed and need to be performed again.

This also applies to the handle_EHLO() hook below.

Deprecated since version 1.3: 使用 5-argument form instead. Support for the 4-argument form will be removed in version 2.0

async handle_EHLO ( server , session , envelope , hostname , responses ) → List [ str ] ¶

参数

• hostname ( str ) – The host name given by the client in the EHLO 命令

• responses ( List [ str ] ) – The ‘planned’ responses to the EHLO 命令 包括 the last 250 HELP 响应。

返回

List of response messages to be sent to the client

Called during EHLO .

The hook MUST return a list containing the desired responses. The returned list should end with 250 HELP

This hook MUST also set the :attr: session.host_name 属性。

重要

It is strongly recommended to not change element [0] of the list (containing the hostname of the SMTP server).

async handle_HELO ( server , session , envelope , hostname ) → str ¶

参数

hostname ( str ) – The host name given by client during HELO

返回

Response message to be sent to the client

This hook is called during HELO .

If implemented, this hook MUST also set the :attr: session.host_name attribute before returning '250 {}'.format(server.hostname) as the status.

async handle_MAIL ( server , session , envelope , address , mail_options ) → str ¶

参数

• address ( str ) – The parsed email address given by the client in the MAIL FROM 命令

• mail_options ( List [ str ] ) – Additional ESMTP MAIL options provided by the client

返回

Response message to be sent to the client

Called during MAIL FROM .

If implemented, this hook MUST also set the envelope.mail_from attribute and it MAY extend envelope.mail_options (which is always a Python list).

async handle_NOOP ( server , session , envelope , arg ) → str ¶

参数

arg ( str ) – All characters following the NOOP 命令

返回

Response message to be sent to the client

Called during NOOP .

handle_PROXY ( server , session , envelope , proxy_data )

参数

• server ( SMTP ) – The SMTP instance invoking the hook.

• session ( Session ) – The Session data so far (see Important note below)

• envelope ( Envelope ) – The Envelope data so far (see Important note below)

• proxy_data ( ProxyData ) – The result of parsing the PROXY Header

返回

Truthy or Falsey, indicating if the connection may continue or not, respectively

Called during PROXY Protocol Handshake.

见 PROXY 协议支持 了解更多信息。

async handle_QUIT ( server , session , envelope ) → str ¶

返回

Response message to be sent to the client

Called during QUIT .

async handle_RCPT ( server , session , envelope , address , rcpt_options ) → str ¶

参数

• address ( str ) – The parsed email address given by the client in the MAIL FROM 命令

• rcpt_options ( List [ str ] ) – Additional ESMTP RCPT options provided by the client

返回

Response message to be sent to the client

Called during RCPT TO .

If implemented, this hook SHOULD append the address to envelope.rcpt_tos and it MAY extend envelope.rcpt_options (both of which are always Python lists).

async handle_RSET ( server , session , envelope ) → str ¶

返回

Response message to be sent to the client

Called during RSET .

async handle_VRFY ( server , session , envelope , address ) → str ¶

参数

address ( str ) – The parsed email address given by the client in the VRFY 命令

返回

Response message to be sent to the client

Called during VRFY .

In addition to the SMTP command hooks, the following hooks can also be implemented by handlers. These have different APIs, and are called 同步 (i.e. they are not coroutines).

handle_STARTTLS ( server , session , envelope ) ¶

If implemented, and if SSL is supported, this method gets called during the TLS handshake phase of connection_made() . It should return True if the handshake succeeded, and False otherwise.

handle_exception ( error ) ¶

If implemented, this method is called when any error occurs during the handling of a connection (e.g. if an smtp_<command>() method raises an exception). The exception object is passed in. This method must return a status string, such as '542 Internal server error' . If the method returns None or raises an exception, an exception will be logged, and a 451 code will be returned to the client.

重要

If client connection is lost, this handler will NOT be called.

内置处理程序 ¶

The following built-in handlers can be imported from aiosmtpd.handlers :

class aiosmtpd.handlers. AsyncMessage ¶

A subclass of the Message handler, it is also an 抽象基类 (it must be subclassed).

The only difference with Message is that handle_message() is called asynchronously .

This class cannot be used on the command line.

class aiosmtpd.handlers. 调试 ¶

This class prints the contents of the received messages to a given output stream. Programmatically, you can pass the stream to print to into the constructor.

When specified on the command line, the (optional) positional argument must either be the string stdout or stderr indicating which stream to use. Examples:

aiosmtpd -c aiosmtpd.handlers.Debugging
aiosmtpd -c aiosmtpd.handlers.Debugging stderr
aiosmtpd -c aiosmtpd.handlers.Debugging stdout
						

class aiosmtpd.handlers. Mailbox ¶

A subclass of the Message handler which adds the messages to a Maildir 。见 邮箱处理程序 了解细节。

When specified on the command line, it accepts exactly one positional argument which is the maildir (i.e, directory where email messages will be stored.) Example:

aiosmtpd -c aiosmtpd.handlers.Mailbox /home/myhome/Maildir
						

class aiosmtpd.handlers. 消息 ¶

This class is an 抽象基类 (it must be subclassed) which converts the message content into a message instance. The class used to create these instances can be passed to the constructor, and defaults to email.message.Message

This message instance gains a few additional headers (e.g. X-Peer , X-MailFrom ，和 X-RcptTo ). You can override this behavior by overriding the prepare_message() method, which takes a session and an envelope. The message instance is then passed to the handler’s handle_message() method. It is this method that must be implemented in the subclass.

prepare_message() and handle_message()`() are both called 同步 .

This class cannot be used on the command line.

class aiosmtpd.handlers. Proxy ¶

This class is a relatively simple SMTP proxy; it forwards messages to a remote host and port. The constructor takes the host name and port as positional arguments.

This class cannot be used on the command line.

重要

Do not confuse this class with the PROXY Protocol ; they are two totally different things.

class aiosmtpd.handlers. Sink ¶

This class just consumes and discards messages. It’s essentially the “no op” handler.

It can be used on the command line, but accepts no positional arguments. Example:

aiosmtpd -c aiosmtpd.handlers.Sink
						

邮箱处理程序 ¶

A convenient handler is the Mailbox handler, which stores incoming messages into a maildir.

To try it, let’s first prepare an ExitStack to automatically clean up after we finish:

>>> from contextlib import ExitStack
>>> from tempfile import TemporaryDirectory
>>> # Clean up the temporary directory at the end
>>> resources = ExitStack()
>>> tempdir = resources.enter_context(TemporaryDirectory())
					

Then, prepare the controller:

>>> import os
>>> from aiosmtpd.controller import Controller
>>> from aiosmtpd.handlers import Mailbox
>>> #
>>> maildir_path = os.path.join(tempdir, 'maildir')
>>> controller = Controller(Mailbox(maildir_path))
>>> controller.start()
>>> # Arrange for the controller to be stopped at the end
>>> ignore = resources.callback(controller.stop)
					

Now we can connect to the server and send it a message…

>>> from smtplib import SMTP
>>> client = SMTP(controller.hostname, controller.port)
>>> client.sendmail('aperson@example.com', ['bperson@example.com'], """\
... From: Anne Person <anne@example.com>
... To: Bart Person <bart@example.com>
... Subject: A test
... Message-ID: <ant>
...
... Hi Bart, this is Anne.
... """)
{}
					

…and a second message…

>>> client.sendmail('cperson@example.com', ['dperson@example.com'], """\
... From: Cate Person <cate@example.com>
... To: Dave Person <dave@example.com>
... Subject: A test
... Message-ID: <bee>
...
... Hi Dave, this is Cate.
... """)
{}
					

…and a third message.

>>> client.sendmail('eperson@example.com', ['fperson@example.com'], """\
... From: Elle Person <elle@example.com>
... To: Fred Person <fred@example.com>
... Subject: A test
... Message-ID: <cat>
...
... Hi Fred, this is Elle.
... """)
{}
					

We open up the mailbox again, and all three messages are waiting for us.

>>> from mailbox import Maildir
>>> from operator import itemgetter
>>> mailbox = Maildir(maildir_path)
>>> messages = sorted(mailbox, key=itemgetter('message-id'))
>>> for message in messages:
...     print(message['Message-ID'], message['From'], message['To'])
<ant> Anne Person <anne@example.com> Bart Person <bart@example.com>
<bee> Cate Person <cate@example.com> Dave Person <dave@example.com>
<cat> Elle Person <elle@example.com> Fred Person <fred@example.com>
					

Cleanup when we’re done.

>>> resources.close()