flanker 0.2

Mailgun Parsing Tools

[](https://drone.io/github.com/mailgun/flanker/latest)

Flanker
=======

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](docs/User Manual.md) as well as the
[API Reference](docs/API Reference.md). A Quickstart Guide is provided below.

## Quickstart Guide

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

```shell
# ubuntu
sudo apt-get install python-dev
# fedora
sudo yum install python-devel
```

If you are using `pip`, simply type:

```shell
pip install flanker
```

If you are cloning from GitHub, you can type:

```shell
git clone [e-mail]:mailgun/flanker.git
cd flanker
python setup.py install
```

### Address Parsing

To parse a single mailbox (display name as well as email address):

```python
>>> from flanker.addresslib import address
>>>
>>> address.parse('Foo [e-mail]')
Foo <[e-mail]>
```

An invalid address is returned as `None`:

```python
>>> from flanker.addresslib import address
>>>
>>> print address.parse('@example.com')
None
```

To parse a single email address (no display name):

```python
>>> from flanker.addresslib import address
>>>
>>> address.parse('[e-mail]', addr_spec_only=True)
[e-mail]
```

To parse an address list:

```python
>>> from flanker.addresslib import address
>>>
>>> address.parse_list('[e-mail], [e-mail], @example.com')
[[e-mail], [e-mail]]
```

To parse an address list as well as return a tuple containing the parsed
addresses and the unparsable portions

```python
>>> from flanker.addresslib import address
>>>
>>> address.parse_list('[e-mail], [e-mail], @example.com', as_tuple=True)
[[e-mail], [e-mail]], ['@example.com']
```

To parse an address list in strict mode:

```python
>>> from flanker.addresslib import address
>>>
>>> address.parse_list('[e-mail], [e-mail], @example.com', strict=True)
[[e-mail], [e-mail]]
```

To validate an email address (parse as well as DNS, MX existence, and ESP grammar checks):

```python
>>> from flanker.addresslib import address
>>>
>>> address.validate_address('[e-mail]')
[e-mail]
```

To validate an address list:

```python
>>> from flanker.addresslib import address
>>>
>>> address.validate_list('[e-mail], [e-mail], @mailgun.com', as_tuple=True)
([[e-mail], [e-mail]], ['@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 <[e-mail]>
To: Alice <[e-mail]>
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:

```python
>>> from flanker import mime
>>>
>>> msg = mime.from_string(message_string)
```

MIME message headers (unicode multi-value dictionary with headers):

```python
>>> 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 <[e-mail]>'),
('To', 'Alice <[e-mail]>'),
('Subject', 'hello, world'),
('Date', 'Mon, 16 Sep 2013 12:43:03 -0700')]
```

Useful content_type member with predicates:

```python
>>> 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:

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