Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/mailgun/flanker

Python email address and Mime parsing library
https://github.com/mailgun/flanker

Last synced: 2 days ago
JSON representation

Python email address and Mime parsing library

Awesome Lists containing this project

README 

        
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 `_ as well as the

`API Reference `_. A Quickstart Guide is provided below.



Python Versions

---------------



Flanker is heavily used by `Mailgun `_ in production with

Python 2.7. The current production version is v0.8.5.



Support for Python 3 was added in v0.9.0 by popular demand from the community.

We are not using Flanker with Python 3 in the house. All we know is that tests

pass with Python 3.6, so use at your own risk. Feel free to report Python 3

specific issues if you see any.



Installing

----------



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 



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 

   To: Alice 

   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--

   

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 '),

    ('To', 'Alice '),

    ('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: 
Hello, Alice



   >>> # None because no enclosed messages exist

   >>> print msg.enclosed

   None