Flanker - email address and MIME parsing for Python ===================================================
.. 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 is an open source parsing library written in Python by the Mailgun Team.
Flanker currently consists of an address parsing library (`flanker.addresslib`) as
well as a MIME parsing library (`flanker.mime`).
Detailed documentation is provided in the `User Manual <https://github.com/mailgun/flanker/blob/master/docs/User%20Manual.md>`_ as well as the
`API Reference <https://github.com/mailgun/flanker/blob/master/docs/API%20Reference.md>`_. A Quickstart Guide is provided below.
Installing
----------
**Flanker was built and tested with Python 2.7.2.**
You can install flanker via `pip` or clone the repo from GitHub.
You'll need Python headers files before you start working with flanker, so install them first:
.. code-block:: bash
# ubuntu
sudo apt-get install python-dev
# fedora
sudo yum install python-devel
If you are using `pip`, simply type:
.. code-block:: bash
pip install flanker
If you are cloning from GitHub, you can type:
.. code-block:: bash
git clone [email protected]:mailgun/flanker.git
cd flanker
pip install -e .
Address Parsing
---------------
To parse a single mailbox (display name as well as email address):
.. code-block:: py
>>> from flanker.addresslib import address
>>>
>>> address.parse('Foo [email protected]')
Foo <[email protected]>
An invalid address is returned as `None`:
.. code-block:: py
>>> from flanker.addresslib import address
>>>
>>> print address.parse('@example.com')
None
To parse a single email address (no display name):
.. code-block:: py
>>> from flanker.addresslib import address
>>>
>>> address.parse('[email protected]', addr_spec_only=True)
[email protected]
To parse an address list:
.. code-block:: py
>>> from flanker.addresslib import address
>>>
>>> address.parse_list('[email protected], [email protected], @example.com')
[[email protected], [email protected]]
To parse an address list as well as return a tuple containing the parsed
addresses and the unparsable portions
.. 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']
To parse an address list in strict mode:
.. code-block:: py
>>> from flanker.addresslib import address
>>>
>>> address.parse_list('[email protected], [email protected], @example.com', strict=True)
[[email protected], [email protected]]
To validate an email address (parse as well as DNS, MX existence, and ESP grammar checks):
.. code-block:: py
>>> from flanker.addresslib import address
>>>
>>> address.validate_address('[email protected]')
[email protected]
To validate an address list:
.. 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'])
MIME Parsing
------------
For the following examples, `message_string` will be set to the following MIME message:
::
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
<p>Hello, <b>Alice</b></p>
--001a11c1d71697c7f004e6856996--
To parse a MIME message:
.. code-block:: py
>>> from flanker import mime
>>>
>>> msg = mime.from_string(message_string)
MIME message headers (unicode multi-value dictionary with headers):
.. 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')]
Useful content_type member with predicates:
.. 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
Decoded body of a message:
.. 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: <p>Hello, <b>Alice</b></p>
>>> # None because no enclosed messages exist
>>> print msg.enclosed
None