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

  * "EmailMessage"

    * "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 messages

  * API do FeedParser

    * "BytesFeedParser"

      * "feed()"

      * "close()"

    * "FeedParser"

  * Parser API

    * "BytesParser"

      * "parse()"

      * "parsebytes()"

    * "BytesHeaderParser"

    * "Parser"

      * "parse()"

      * "parsestr()"

    * "HeaderParser"

    * "message_from_bytes()"

    * "message_from_binary_file()"

    * "message_from_string()"

    * "message_from_file()"

  * Additional notes

* "email.generator": Generating MIME documents

  * "BytesGenerator"

    * "flatten()"

    * "clone()"

    * "write()"

  * "Generator"

    * "flatten()"

    * "clone()"

    * "write()"

  * "DecodedGenerator"

* "email.policy": Policy Objects

  * "Policy"

    * "max_line_length"

    * "linesep"

    * "cte_type"

    * "raise_on_defect"

    * "mangle_from_"

    * "message_factory"

    * "verify_generated_headers"

    * "clone()"

    * "handle_defect()"

    * "register_defect()"

    * "header_max_count()"

    * "header_source_parse()"

    * "header_store_parse()"

    * "header_fetch_parse()"

    * "fold()"

    * "fold_binary()"

  * "EmailPolicy"

    * "utf8"

    * "refold_source"

    * "header_factory"

    * "content_manager"

    * "header_max_count()"

    * "header_source_parse()"

    * "header_store_parse()"

    * "header_fetch_parse()"

    * "fold()"

    * "fold_binary()"

  * "default"

  * "SMTP"

  * "SMTPUTF8"

  * "HTTP"

  * "strict"

  * "Compat32"

    * "mangle_from_"

    * "header_source_parse()"

    * "header_store_parse()"

    * "header_fetch_parse()"

    * "fold()"

    * "fold_binary()"

  * "compat32"

* "email.errors": Exception and Defect classes

  * "MessageError"

  * "MessageParseError"

  * "HeaderParseError"

  * "BoundaryError"

  * "MultipartConversionError"

  * "HeaderWriteError"

  * "MessageDefect"

  * "HeaderDefect"

* "email.headerregistry": Custom Header Objects

  * "BaseHeader"

    * "name"

    * "defects"

    * "max_count"

    * "fold()"

  * "UnstructuredHeader"

  * "DateHeader"

    * "datetime"

  * "AddressHeader"

    * "groups"

    * "addresses"

  * "SingleAddressHeader"

    * "address"

  * "MIMEVersionHeader"

    * "version"

    * "major"

    * "minor"

  * "ParameterizedMIMEHeader"

    * "params"

  * "ContentTypeHeader"

    * "content_type"

    * "maintype"

    * "subtype"

  * "ContentDispositionHeader"

    * "content_disposition"

  * "ContentTransferEncoding"

    * "cte"

  * "HeaderRegistry"

    * "map_to_type()"

    * "__getitem__()"

    * "__call__()"

  * "Address"

    * "display_name"

    * "username"

    * "domain"

    * "addr_spec"

    * "__str__()"

  * "Group"

    * "display_name"

    * "addresses"

    * "__str__()"

* "email.contentmanager": Managing MIME Content

  * "ContentManager"

    * "get_content()"

    * "set_content()"

    * "add_get_handler()"

    * "add_set_handler()"

  * Content Manager Instances

    * "raw_data_manager"

      * "get_content()"

      * "set_content()"

* "email": Exemplos

API legada

* "email.message.Message": Representing an email message using the
  "compat32" API

  * "Message"

    * "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 scratch

  * "MIMEBase"

  * "MIMENonMultipart"

  * "MIMEMultipart"

  * "MIMEApplication"

  * "MIMEAudio"

  * "MIMEImage"

  * "MIMEMessage"

  * "MIMEText"

* "email.header": Internationalized headers

  * "Header"

    * "append()"

    * "encode()"

    * "__str__()"

    * "__eq__()"

    * "__ne__()"

  * "decode_header()"

  * "make_header()"

* "email.charset": Representing character sets

  * "Charset"

    * "input_charset"

    * "header_encoding"

    * "body_encoding"

    * "output_charset"

    * "input_codec"

    * "output_codec"

    * "get_body_encoding()"

    * "get_output_charset()"

    * "header_encode()"

    * "header_encode_lines()"

    * "body_encode()"

    * "__str__()"

    * "__eq__()"

    * "__ne__()"

  * "add_charset()"

  * "add_alias()"

  * "add_codec()"

* "email.encoders": Encoders

  * "encode_quopri()"

  * "encode_base64()"

  * "encode_7or8bit()"

  * "encode_noop()"

* "email.utils": Utilitários diversos

  * "localtime()"

  * "make_msgid()"

  * "quote()"

  * "unquote()"

  * "parseaddr()"

  * "formataddr()"

  * "getaddresses()"

  * "parsedate()"

  * "parsedate_tz()"

  * "parsedate_to_datetime()"

  * "mktime_tz()"

  * "formatdate()"

  * "format_datetime()"

  * "decode_rfc2231()"

  * "encode_rfc2231()"

  * "collapse_rfc2231_value()"

  * "decode_params()"

* "email.iterators": Iteradores

  * "body_line_iterator()"

  * "typed_subpart_iterator()"

  * "_structure()"

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 "mailbox"
     Ferramentas para criar, ler, e gerenciar coleções de mensagem em
     disco usando vários formatos padrão.
