"email" --- An email and MIME handling package
**********************************************

**Código fuente** Lib/email/__init__.py

======================================================================

The "email" package is a library for managing email messages.  It is
specifically *not* designed to do any sending of email messages to
SMTP (**RFC 2821**), NNTP, or other servers; those are functions of
modules such as "smtplib".  The "email" package attempts to be as RFC-
compliant as possible, supporting **RFC 5322** and **RFC 6532**, as
well as such MIME-related RFCs as **RFC 2045**, **RFC 2046**, **RFC
2047**, **RFC 2183**, and **RFC 2231**.

La estructura general del paquete de correo electrónico se puede
dividir en tres componentes principales, más un cuarto componente que
controla el comportamiento de los otros componentes.

El componente central del paquete es un "modelo de objetos" que
representa los mensajes de correo electrónico. Una aplicación
interactúa con el paquete principalmente a través de la interfaz del
modelo de objetos definida en el submódulo "message". La aplicación
puede usar esta API para hacer preguntas sobre un correo electrónico
existente, para construir un nuevo correo electrónico o para agregar o
eliminar subcomponentes de correo electrónico que utilizan la misma
interfaz de modelo de objetos. Es decir, siguiendo la naturaleza de
los mensajes de correo electrónico y sus subcomponentes MIME, el
modelo de objetos de correo electrónico es una estructura de árbol de
objetos que proporcionan la API "EmailMessage".

Los otros dos componentes principales del paquete son "parser" y
"generator". El parser toma la versión serializada de un mensaje de
correo electrónico (una secuencia de bytes) Y la convierte en un árbol
de objetos "EmailMessage". El generador toma un "EmailMessage" y lo
convierte de nuevo en un flujo de bytes serializado. (El analizador y
el generador también manejan flujos de caracteres de texto, pero se
desaconseja este uso ya que es demasiado fácil terminar con mensajes
que no son válidos de una forma u otra).

El componente de control es el módulo de "policy". Cada "EmailMessage"
cada "generator", y cada "parser" tiene un objeto de "policy" asociado
que controla su comportamiento. Por lo general, una aplicación solo
necesita especificar la política cuando se crea un "EmailMessage" , ya
sea instanciando directamente un "EmailMessage" para crear un nuevo
correo electrónico o analizando un flujo de entrada con un "parser".
Pero la política se puede cambiar cuando el mensaje se serializa
mediante un "generator". Esto permite, por ejemplo, analizar un
mensaje de correo electrónico genérico desde el disco, pero
serializarlo utilizando la configuración estándar de SMTP al enviarlo
a un servidor de correo electrónico.

The email package does its best to hide the details of the various
governing RFCs from the application.  Conceptually the application
should be able to treat the email message as a structured tree of
Unicode text and binary attachments, without having to worry about how
these are represented when serialized.  In practice, however, it is
often necessary to be aware of at least some of the rules governing
MIME messages and their structure, specifically the names and nature
of the MIME "content types" and how they identify multipart documents.
For the most part this knowledge should only be required for more
complex applications, and even then it should only be the high level
structure in question, and not the details of how those structures are
represented.  Since MIME content types are used widely in modern
internet software (not just email), this will be a familiar concept to
many programmers.

The following sections describe the functionality of the "email"
package. We start with the "message" object model, which is the
primary interface an application will use, and follow that with the
"parser" and "generator" components.  Then we cover the "policy"
controls, which completes the treatment of the main components of the
library.

Las siguientes tres secciones cubren las excepciones que puede generar
el paquete y los defectos (incumplimiento de las RFC) que el "parser"
puede detectar. Luego cubrimos los subcomponentes "headerregistry" y
"contentmanager", que proporcionan herramientas para realizar una
manipulación más detallada de los encabezados y cargas útiles,
respectivamente. Ambos componentes contienen características
relevantes para consumir y producir mensajes no triviales, pero
también documentan sus API de extensibilidad, que serán de interés
para aplicaciones avanzadas.

A continuación, se muestra un conjunto de ejemplos del uso de las
partes fundamentales de las API cubiertas en las secciones anteriores.

The foregoing represent the modern (Unicode friendly) API of the email
package. The remaining sections, starting with the "Message" class,
cover the legacy "compat32" API that deals much more directly with the
details of how email messages are represented.  The "compat32" API
does *not* hide the details of the RFCs from the application, but for
applications that need to operate at that level, they can be useful
tools.  This documentation is also relevant for applications that are
still using the "compat32" API for backward compatibility reasons.

Distinto en la versión 3.6: Documentos reorganizados y reescritos para
promover la nueva API "EmailMessage"/"EmailPolicy".

Contents of the "email" package documentation:

* "email.message": Representing an email message

* "email.parser": Parsing email messages

  * API *FeedParser*

  * API *Parser*

  * Notas adicionales

* "email.generator": Generating MIME documents

* "email.policy": Policy Objects

* "email.errors": Exception and Defect classes

* "email.headerregistry": Custom Header Objects

* "email.contentmanager": Managing MIME Content

  * Instancias gestoras de contenido

* "email": Ejemplos

API heredada:

* "email.message.Message": Representar un mensaje de correo
  electrónico usando la API "compat32"

* "email.mime": Creating email and MIME objects from scratch

* "email.header": Internationalized headers

* "email.charset": Representing character sets

* "email.encoders": Encoders

* "email.utils": Miscellaneous utilities

* "email.iterators": Iterators

Ver también:

  Módulo "smtplib"
     Cliente SMTP (Protocolo simple de transporte de correo)

  Módulo "poplib"
     Cliente POP (Protocolo de oficina postal)

  Módulo "imaplib"
     Cliente IMAP (Protocolo de acceso a mensajes de Internet)

  Módulo "mailbox"
     Herramientas para crear, leer y administrar colecciones de
     mensajes en disco utilizando una variedad de formatos estándar.
