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:

API heredada:

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.