.. image:: https://travis-ci.org/mailgun/flanker.svg?branch=master :target: https://travis-ci.org/mailgun/flanker
.. image:: https://coveralls.io/repos/github/mailgun/flanker/badge.svg?branch=master :target: https://coveralls.io/github/mailgun/flanker?branch=master
Flanker 是由 Mailgun 团队用 Python 编写的开源解析库。Flanker 目前包含一个地址解析库（flanker.addresslib）以及一个 MIME 解析库（flanker.mime）。
详细的文档见 用户手册 <https://github.com/mailgun/flanker/blob/master/docs/User%20Manual.md>_ 以及 API 参考 <https://github.com/mailgun/flanker/blob/master/docs/API%20Reference.md>_。下面提供一份快速入门指南。
Flanker 在生产环境中被 Mailgun <www.mailgun.com>_ 大量使用，运行于 Python 2.7。当前生产版本为 v0.8.5。
应社区的强烈要求，v0.9.0 已加入对 Python 3 的支持。我们内部并未在 Python 3 下使用 Flanker。我们只知道测试在 Python 3.6 下能通过，因此请自担风险使用。如果你发现任何 Python 3 特有的问题，欢迎报告。
你可以通过 pip 安装 flanker，也可以从 GitHub 克隆仓库。
在开始使用 flanker 之前，你需要先安装 Python 头文件，请先安装它们：
.. code-block:: bash
sudo apt-get install python-dev
sudo yum install python-devel
如果你使用 pip，直接输入：
.. code-block:: bash
pip install flanker
如果你从 GitHub 克隆，可以输入：
.. code-block:: bash
git clone [email protected]:mailgun/flanker.git cd flanker pip install -e .
要解析单个邮箱（包括显示名称和电子邮件地址）：
.. code-block:: py
from flanker.addresslib import address
address.parse('Foo [email protected]') Foo [email protected]
无效地址将返回 None：
.. code-block:: py
from flanker.addresslib import address
print address.parse('@example.com') None
要解析单个电子邮件地址（不含显示名称）：
.. code-block:: py
from flanker.addresslib import address
address.parse('[email protected]', addr_spec_only=True) [email protected]
要解析地址列表：
.. code-block:: py
from flanker.addresslib import address
address.parse_list(['[email protected], [email protected], @example.com']) [[email protected], [email protected]]
要解析地址列表，并返回一个包含已解析地址和无法解析部分的元组：
.. code-block:: py
from flanker.addresslib import address
address.parse_list(['[email protected], [email protected], @example.com'], as_tuple=True) [[email protected], [email protected]], ['@example.com']
在严格模式下解析地址列表：
.. code-block:: py
from flanker.addresslib import address
address.parse_list(['[email protected], [email protected], @example.com'], strict=True) [[email protected], [email protected]]
验证电子邮件地址（包括解析、DNS/MX 记录存在性以及 ESP 语法检查）：
.. code-block:: py
from flanker.addresslib import address
address.validate_address('[email protected]') [email protected]
要验证地址列表：
.. code-block:: py
from flanker.addresslib import address
address.validate_list(['[email protected], [email protected], @mailgun.com'], as_tuple=True) ([[email protected], [email protected]], ['@mailgun.com'])
在以下示例中，message_string 将设置为以下 MIME 消息：
::
MIME-Version: 1.0 Content-Type: multipart/alternative; boundary=001a11c1d71697c7f004e6856996 From: Bob [email protected] To: Alice [email protected] Subject: hello, world Date: Mon, 16 Sep 2013 12:43:03 -0700
--001a11c1d71697c7f004e6856996 Content-Type: text/plain; charset=us-ascii
Hello, Alice
--001a11c1d71697c7f004e6856996 Content-Type: text/html; charset=us-ascii
Hello, Alice
--001a11c1d71697c7f004e6856996--
要解析 MIME 消息：
.. code-block:: py
from flanker import mime
msg = mime.from_string(message_string)
MIME 消息头（带 headers 的 unicode 多值字典）：
.. code-block:: py
from flanker import mime
msg = mime.from_string(message_string) msg.headers.items() [('Mime-Version', '1.0'), ('Content-Type', ('multipart/alternative', {'boundary': u'001a11c1d71697c7f004e6856996'})), ('From', 'Bob [email protected]'), ('To', 'Alice [email protected]'), ('Subject', 'hello, world'), ('Date', 'Mon, 16 Sep 2013 12:43:03 -0700')]
带有谓词方法的实用 content_type 成员：
.. code-block:: py
from flanker import mime msg = mime.from_string(message_string)
msg.content_type.is_multipart() True
msg.content_type.is_singlepart() False
msg.content_type.is_message_container() False
消息解码后的正文：
.. code-block:: py
from flanker import mime msg = mime.from_string(message_string)
None because message is multipart
print msg.body None
for part in msg.parts: print 'Content-Type: {} Body: {}'.format(part, part.body)
Content-Type: (text/plain) Body: Hello, Alice Content-Type: (text/html) Body:
Hello, Alice
None because no enclosed messages exist
print msg.enclosed None
