Flanker - análise de endereços de e-mail e MIME para 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

O Flanker é uma biblioteca de análise de código aberto escrita em Python pela equipe do Mailgun. Atualmente, o Flanker é composto por uma biblioteca de análise de endereços (flanker.addresslib) e por uma biblioteca de análise de MIME (flanker.mime).

Documentação detalhada é fornecida no Manual do Usuário <https://github.com/mailgun/flanker/blob/master/docs/User%20Manual.md>_ e na Referência da API <https://github.com/mailgun/flanker/blob/master/docs/API%20Reference.md>_. Um Guia de Início Rápido é fornecido abaixo.

Versões do Python

O Flanker é amplamente utilizado pelo Mailgun <www.mailgun.com>_ em produção com Python 2.7. A versão de produção atual é a v0.8.5.

O suporte para Python 3 foi adicionado na v0.9.0 por demanda popular da comunidade. Não usamos o Flanker com Python 3 internamente. Tudo o que sabemos é que os testes passam com Python 3.6; portanto, use por sua conta e risco. Sinta-se à vontade para relatar problemas específicos do Python 3, caso veja algum.

Instalação

Você pode instalar o flanker via pip ou clonar o repositório do GitHub.

Você precisará dos arquivos de cabeçalho do Python antes de começar a trabalhar com o flanker, portanto, instale-os primeiro:

.. code-block:: bash

ubuntu

sudo apt-get install python-dev

fedora

sudo yum install python-devel

Se você estiver usando pip, basta digitar:

.. code-block:: bash

pip install flanker

Se estiver clonando do GitHub, você pode digitar:

.. code-block:: bash

git clone [email protected]:mailgun/flanker.git cd flanker pip install -e .

Análise de Endereços

Para analisar uma única caixa de correio (nome de exibição e endereço de e-mail):

.. code-block:: py

from flanker.addresslib import address

address.parse('Foo [email protected]') Foo [email protected]

Um endereço inválido é retornado como None:

.. code-block:: py

from flanker.addresslib import address

print address.parse('@example.com') None

Para analisar um único endereço de e-mail (sem nome de exibição):

.. code-block:: py

from flanker.addresslib import address

address.parse('[email protected]', addr_spec_only=True) [email protected]

Para analisar uma lista de endereços:

.. code-block:: py

from flanker.addresslib import address

address.parse_list(['[email protected], [email protected], @example.com']) [[email protected], [email protected]]

Para analisar uma lista de endereços e também retornar uma tupla contendo os endereços analisados e as porções não analisáveis

.. 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']

Para analisar uma lista de endereços no modo estrito:

.. code-block:: py

from flanker.addresslib import address

address.parse_list(['[email protected], [email protected], @example.com'], strict=True) [[email protected], [email protected]]

Para validar um endereço de e-mail (analisa e também verifica DNS, existência de MX e regras de gramática do ESP):

.. code-block:: py

from flanker.addresslib import address

address.validate_address('[email protected]') [email protected]

Para validar uma lista de endereços:

.. 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'])

Análise de MIME

Para os exemplos a seguir, message_string será definida como a seguinte mensagem 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--

Para analisar uma mensagem MIME:

.. code-block:: py

from flanker import mime

msg = mime.from_string(message_string)

Cabeçalhos da mensagem MIME (dicionário unicode multivalorado com cabeçalhos):

.. 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')]

Membro content_type útil com predicados:

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

Corpo decodificado de uma mensagem:

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