email
— Um e-mail e um pacote MIME manipulável¶
Código-fonte: Lib/email/__init__.py
O pacote email
é uma biblioteca para gerenciar mensagens de e-mail. Ela foi especificamente não projetada para enviar mensagens de e-mail para SMTP (RFC 2821), NNTP ou outros servidores; essas são funções de módulos como smtplib
e nntplib
. O pacote email
tenta ser o mais compatível possível com RFC, suportando RFC 5322 e RFC 6532, bem como os RFCs relacionados ao MIME como RFC 2045, RFC 2046, RFC 2047, RFC 2183 e RFC 2231.
No geral a estrutura do pacote de e-mail pode ser dividida em três componentes principais, mais um quarto componente que controla o comportamento dos outros componentes.
O componente central do pacote é um “modelo de objeto” que representa mensagens de e-mail. Uma aplicação interage com o pacote principalmente através da interface do modelo de objeto definida no submódulo message
. A aplicação pode usar essa API para fazer perguntas sobre um e-mail existente, construir um novo e-mail ou adicionar ou remover subcomponentes de e-mail que usam a mesma interface de modelo de objeto. Ou seja, seguindo a natureza das mensagens de e-mail e seus subcomponentes MIME, o modelo de objeto de e-mail é uma estrutura em árvore de objetos que fornecem a API EmailMessage
.
Os outros dois componentes principais do pacote são parser
e generator
. O analisador sintático pega a versão serializada de uma mensagem de e-mail (um fluxo de bytes) e a converte em uma árvore de objetos EmailMessage
. O gerador pega um EmailMessage
e o transforma novamente em um fluxo de bytes serializado. (O analisador sintático e o gerador também lidam com fluxos de caracteres de texto, mas esse uso é desencorajado, pois é muito fácil terminar com mensagens que não são válidas de uma maneira ou de outra.)
O componente de controle é o módulo policy
. Cada EmailMessage
, cada generator
e cada parser
tem um objeto associado policy
que controla seu comportamento. Normalmente, uma aplicação precisa especificar a política apenas quando uma EmailMessage
é criada, instanciando diretamente uma EmailMessage
para criar um novo e-mail ou analisando um fluxo de entrada usando um parser
. Mas a política pode ser alterada quando a mensagem é serializada usando um generator
. Isso permite, por exemplo, analisar uma mensagem de e-mail genérica do disco, mas serializá-la usando as configurações SMTP padrão ao enviá-la para um servidor de e-mail.
O pacote de e-mail faz o possível para ocultar os detalhes das várias RFCs em vigor da aplicação. Conceitualmente, a aplicação deve tratar a mensagem de e-mail como uma árvore estruturada de texto unicode e anexos binários, sem ter que se preocupar com a forma como eles são representados quando serializados. Na prática, no entanto, muitas vezes é necessário estar ciente de pelo menos algumas das regras que regem as mensagens MIME e sua estrutura, especificamente os nomes e a natureza dos “tipos de conteúdo” MIME e como eles identificam documentos com várias partes. Na maioria das vezes, esse conhecimento só deve ser necessário para aplicações mais complexos e, mesmo assim, deve ser apenas a estrutura de alto nível em questão, e não os detalhes de como essas estruturas são representadas. Como os tipos de conteúdo MIME são amplamente utilizados no software moderno da Internet (não apenas no e-mail), este será um conceito familiar para muitos programadores.
As seções a seguir descrevem a funcionalidade do pacote email
. Começamos com o modelo de objeto message
, que é a interface principal que uma aplicação usará, e seguimos com os componentes de parser
e generator
. Em seguida, abordamos os controles policy
, que concluem o tratamento dos principais componentes da biblioteca.
As próximas três seções cobrem as exceções que o pacote pode apresentar e os defeitos (não conformidade com as RFCs) que o parser
pode detectar. A seguir, abordamos os subcomponentes headerregistry
e os subcomponentes contentmanager
, que fornecem ferramentas para manipulação mais detalhada de cabeçalhos e cargas úteis, respectivamente. Ambos os componentes contêm recursos relevantes para consumir e produzir mensagens não triviais, mas também documentam suas APIs de extensibilidade, que serão de interesse para aplicações avançadas.
A seguir, é apresentado um conjunto de exemplos de uso das partes fundamentais das APIs abordadas nas seções anteriores.
O exposto acima representa a API moderna (compatível com unicode) do pacote de e-mail. As seções restantes, começando com a classe Message
, cobrem a API legada compat32
que lida muito mais diretamente com os detalhes de como as mensagens de e-mail são representadas. A API compat32
não oculta os detalhes dos RFCs da aplicação, mas para aplicações que precisam operar nesse nível, eles podem ser ferramentas úteis. Esta documentação também é relevante para aplicações que ainda estão usando a API compat32
por motivos de compatibilidade com versões anteriores.
Alterado na versão 3.6: Documentos reorganizados e reescritos para promover a nova API EmailMessage
/EmailPolicy
.
Conteúdos da documentação do pacote email
:
email.message
: Representing an email messageEmailMessage
as_string()
__str__()
as_bytes()
__bytes__()
is_multipart()
set_unixfrom()
get_unixfrom()
__len__()
__contains__()
__getitem__()
__setitem__()
__delitem__()
keys()
values()
items()
get()
get_all()
add_header()
replace_header()
get_content_type()
get_content_maintype()
get_content_subtype()
get_default_type()
set_default_type()
set_param()
del_param()
get_filename()
get_boundary()
set_boundary()
get_content_charset()
get_charsets()
is_attachment()
get_content_disposition()
walk()
get_body()
iter_attachments()
iter_parts()
get_content()
set_content()
make_related()
make_alternative()
make_mixed()
add_related()
add_alternative()
add_attachment()
clear()
clear_content()
preamble
epilogue
defects
MIMEPart
email.parser
: Parsing email messagesemail.generator
: Generating MIME documentsemail.policy
: Policy Objectsemail.errors
: Exception and Defect classesemail.headerregistry
: Custom Header Objectsemail.contentmanager
: Managing MIME Contentemail
: Exemplos
API legada
email.message.Message
: Representing an email message using thecompat32
APIMessage
as_string()
__str__()
as_bytes()
__bytes__()
is_multipart()
set_unixfrom()
get_unixfrom()
attach()
get_payload()
set_payload()
set_charset()
get_charset()
__len__()
__contains__()
__getitem__()
__setitem__()
__delitem__()
keys()
values()
items()
get()
get_all()
add_header()
replace_header()
get_content_type()
get_content_maintype()
get_content_subtype()
get_default_type()
set_default_type()
get_params()
get_param()
set_param()
del_param()
set_type()
get_filename()
get_boundary()
set_boundary()
get_content_charset()
get_charsets()
get_content_disposition()
walk()
preamble
epilogue
defects
email.mime
: Creating email and MIME objects from scratchemail.header
: Internationalized headersemail.charset
: Representing character setsemail.encoders
: Encodersemail.utils
: Utilitários diversosemail.iterators
: Iteradores
Ver também
- Módulo
smtplib
Cliente SMTP (Protocolo Simples de Envio de E-mail)
- Módulo
poplib
Cliente POP (Post Office Protocol)
- Módulo
imaplib
Cliente IMAP (Internet Message Access Protocol)
- Módulo
nntplib
Cliente NNTP (Network News Transport Protocol)
- Módulo
mailbox
Ferramentas para criar, ler, e gerenciar coleções de mensagem em disco usando vários formatos padrão.