email.parser: Parsing email messages

Código fuente: Lib/email/parser.py

Se pueden construir estructuras de objetos de mensaje de dos formas: pueden ser creados de puro invento al crear un objeto EmailMessage, añadir encabezados usando la interfaz de diccionario, y añadir carga(s) usando el método set_content() y otros relacionados, o pueden ser creados al analizar una representación serializada de un mensaje de correo electrónico.

El paquete email proporciona un analizador estándar que entiende la mayoría de estructuras de documentos de correo electrónico, incluyendo documentos MIME. Le puedes pasar al analizador bytes, una cadena de caracteres o una archivo de objeto, y el analizador te retornará la instancia EmailMessage raíz de la estructura del objeto. Para mensajes simples que no sean MIME, la carga de su objeto raíz probablemente será una cadena de caracteres conteniendo el texto o el mensaje. Para mensajes MIME, el objeto raíz retornará True de su método is_multipart(), y las subpartes pueden ser accedidas a través de los métodos de manipulación de carga, tales como get_body(), iter_parts(), y walk().

De hecho hay dos interfaces de analizadores disponibles para usar, la API Parser y la API progresiva FeedParser. La API Parser es más útil si tú tienes el texto del mensaje entero en memoria, o si el mensaje entero reside en un archivo en el sistema. FeedParser es más apropiado cuando estás leyendo el mensaje de un stream que puede ser bloqueado esperando más entrada (tal como leer un mensaje de correo electrónico de un socket). El FeedParser puede consumir y analizar el mensaje de forma progresiva, y sólo retorna el objeto raíz cuando cierras el analizador.

Tenga en cuenta que el analizador puede ser extendido en formas limitadas, y por supuesto puedes implementar tu propio analizador completamente desde cero. Toda la lógica que conecta el analizador empaquetado del paquete email y la clase EmailMessage está encarnada en la clase Policy, por lo que un analizador personalizado puede crear árboles de objetos mensaje en cualquier forma que encuentre necesario al implementar versiones personalizadas de los métodos apropiados de Policy.

API FeedParser

La clase BytesFeedParser, importado del módulo email.feedparser, proporciona una API que es propicia para el análisis progresivo de mensajes de correo electrónico, tal como sería necesario cuando se esté leyendo el texto de un mensaje de correo electrónico de una fuente que puede bloquear (tal como un socket). Desde luego se puede usar la clase BytesFeedParser para analizar un mensaje de correo electrónico completamente contenido en un bytes-like object, cadena de caracteres, o archivo, pero la API BytesParser puede ser más conveniente para tales casos de uso. Las semánticas y resultados de las dos API de los analizadores son idénticas.

La API de BytesFeedParser es simple; puedes crear una instancia, le proporcionas un montón de bytes hasta que no haya más necesidad de hacerlo, entonces cierras el analizador para recuperar el objeto del mensaje raíz. El BytesFeedParser es extremadamente preciso cuando está analizando mensajes conformes al estándar, y hace un buen trabajo al analizar mensajes no conformes, proporcionando información acerca de cómo un mensaje fue considerado inservible. Ingresará una lista de cualquier problema que encontró en el atributo defects del objeto mensaje. Véase el módulo email.errors para la lista de defectos que puede encontrar.

Aquí está el API para BytesFeedParser:

class email.parser.BytesFeedParser(_factory=None, *, policy=policy.compat32)

Crea una instancia de BytesFeedParser. El argumento opcional _factory es un invocable sin argumentos; si no se especifica, usa el message_factory de policy. Llama a _factory cuando sea necesario un nuevo objeto mensaje.

Si se especifica policy, usa las reglas que especifica para actualizar la representación del mensaje. Si policy no está puesta, usa la política (policy) compat32, que mantiene compatibilidad con la versión 3.2 de Python del paquete de correo electrónico y proporciona a Message como la fábrica por defecto. Todas las otras políticas proveen a EmailMessage como el _factory por defecto. Para más información en lo demás que policy controla, véase la documentación policy.

Nota: La palabra clave *policy* siempre debe estar especificada; El valor por defecto cambiará a email.policy.default en una versión futura de Python.

Added in version 3.2.

Distinto en la versión 3.3: Se añadió la palabra clave policy.

Distinto en la versión 3.6: _factory es por defecto la policy message_factory.

feed(data)

Le proporciona al analizador algunos datos más. data debe ser un bytes-like object conteniendo una o más líneas. Las líneas pueden ser parciales y el analizador va a juntar tales líneas parciales apropiadamente. las líneas pueden tener cualquiera de las tres terminaciones de línea comunes: retorno de cargo (retorno de cargo), nueva línea (newline), o retorno de cargo y nueva línea (pueden ser mezclados).

close()

Completa el análisis de todos los datos previamente proporcionados y retorna la raíz del objeto mensaje. No está definido lo que pasa si se llama a feed() después de que este método haya sido llamado.

class email.parser.FeedParser(_factory=None, *, policy=policy.compat32)

Funciona como BytesFeedParser excepto que la entrada al método feed() no debe ser una cadena de caracteres. Esto es utilidad limitada, ya que la única manera de que tal mensaje sea válido es que sólo contenga texto ASCII o, si utf8 es True, sin binarios adjuntos.

Distinto en la versión 3.3: Se añadió la palabra clave policy.

API Parser

La clase BytesParser, importado del módulo email.parser, proporciona una API que puede ser usada para analizar un mensaje cuando el contenido completo del mensaje esté disponible en un bytes-like object o archivo. El módulo email.parser también proporciona a Parser para analizar cadenas de caracteres, y analizadores de sólo cabeceras, BytesHeaderParser y HeaderParser que pueden ser usados si sólo estás interesado en las cabeceras del mensaje. BytesHeaderParser y HeaderParser puede ser más rápidos en estas situaciones, ya que no intentan analizar el cuerpo del mensaje, en vez de eso configuran la carga al cuerpo puro.

class email.parser.BytesParser(_class=None, *, policy=policy.compat32)

Crea una instancia de BytesParser. Los argumentos _class y policy tiene el mismo significado y semántica que los argumentos _factory y policy de BytesFeedParser.

Nota: La palabra clave *policy* siempre debe estar especificada; El valor por defecto cambiará a email.policy.default en una versión futura de Python.

Distinto en la versión 3.3: Se eliminó el argumento strict que fue deprecado en 2.4. Se añadió la palabra clave policy.

Distinto en la versión 3.6: _class es por defecto la política message_factory.

parse(fp, headersonly=False)

Lee todos los datos del objeto binario parecido a archivo fp, analiza los bytes resultantes, y retorna el objeto mensaje. fp debe soportar tanto el método readline() como el método read().

Los bytes contenidos en fp deben ser formateados como un bloque de cabeceras de estilo y líneas de continuación de cabecera de RFC 5322 (o, si utf8 es True, RFC 6532). El bloque cabecera se termina o al final de los datos o por una línea blanca. Después del bloque de cabecera esta él cuerpo del mensaje (que puede contener subpartes codificadas como MIME, incluyendo subpartes con un Content-Transfer-Encoding de 8bit).

El argumento opcional headersonly es un flag que especifica si se debe analizar después de leer las cabeceras o no. El valor por defecto es False, significando que analiza el contenido entero del archivo.

parsebytes(bytes, headersonly=False)

Similar al método parse(), excepto que toma un bytes-like object en vez de un objeto similar a un archivo. Llamar a este método en un bytes-like object es equivalente a envolver a bytes en una instancia de BytesIO primero y llamar a parse().

El argumento opcional headersonly es como el método parse().

Added in version 3.2.

class email.parser.BytesHeaderParser(_class=None, *, policy=policy.compat32)

Exactamente como BytesParser, excepto que headersonly es por defecto True.

Added in version 3.3.

class email.parser.Parser(_class=None, *, policy=policy.compat32)

Esta clase es paralela a BytesParser, pero trata entradas de cadenas de caracteres.

Distinto en la versión 3.3: Se eliminó el argumento strict. Se añadió la palabra clave policy.

Distinto en la versión 3.6: _class es por defecto la política message_factory.

parse(fp, headersonly=False)

Lee todos los datos del modo texto del objeto parecido a archivo fp, analiza el texto resultante, y retorna el objeto mensaje raíz. fp debe soportar tanto el método readline() y el método read() en objetos parecidos a archivos.

Además de el requisito del modo texto, este método opera como BytesParser.parse().

parsestr(text, headersonly=False)

Similar al método parse(), excepto que toma un objeto de cadena de caracteres de un objeto similar a un archivo. Llamar a este método en una cadena de caracteres es equivalente a envolver a text en una instancia de StringIO primero y llamar a parse().

El argumento opcional headersonly es como el método parse().

class email.parser.HeaderParser(_class=None, *, policy=policy.compat32)

Exactamente como Parser, excepto que headersonly es por defecto True.

Ya que crear una estructura de un objeto mensaje de una cadena de caracteres o un objeto archivo es una tarea tan común, Se proporcionaron 4 funciones como una conveniencia. Están disponibles en paquete de espacio de nombres de alto nivel email.

email.message_from_bytes(s, _class=None, *, policy=policy.compat32)

Retorna una estructura del objeto mensaje de un bytes-like object. Esto es equivalente a BytesParser().parsebytes(s). El argumento opcional _class y policy son interpretados como sucede con el constructor de clase BytesParser.

Added in version 3.2.

Distinto en la versión 3.3: Se eliminó el argumento strict. Se añadió la palabra clave policy.

email.message_from_binary_file(fp, _class=None, *, policy=policy.compat32)

Retorna una estructura árbol del objeto mensaje de un file object binario abierto. Esto es equivalente a BytesParser().parse(fp). _class y policy son interpretados como sucede con el constructor de clase BytesParser.

Added in version 3.2.

Distinto en la versión 3.3: Se eliminó el argumento strict. Se añadió la palabra clave policy.

email.message_from_string(s, _class=None, *, policy=policy.compat32)

Retorna una estructura del objeto mensaje de una cadena de caracteres. Esto es equivalente a Parser().parsestr(s). _class y policy son interpretados como sucede con el constructor de clase Parser.

Distinto en la versión 3.3: Se eliminó el argumento strict. Se añadió la palabra clave policy.

email.message_from_file(fp, _class=None, *, policy=policy.compat32)

Retorna una estructura árbol del objeto mensaje de un file object abierto. Esto es equivalente a Parser().parse(fp). _class y policy son interpretados como sucede con el constructor de clase Parser.

Distinto en la versión 3.3: Se eliminó el argumento strict. Se añadió la palabra clave policy.

Distinto en la versión 3.6: _class es por defecto la política message_factory.

Aquí está un ejemplo de cómo puedes usar message_from_bytes() en una entrada interactiva de Python:

>>> import email
>>> msg = email.message_from_bytes(myBytes)

Notas adicionales

Aquí están algunas notas sobre la semántica del análisis:

  • La mayoría de los mensajes de tipo que no son multipart son actualizados como un solo objeto mensaje con una carga de cadena de caracteres. Estos objetos retornarán False para is_multipart(), y iter_parts() cederá (yield) una lista vacía.

  • Todos los mensajes de tipo multipart serán analizados como un objeto mensaje contenedor con una lista de objetos sub-mensajes para sus cargas. El mensaje del contenedor externo retornará True para is_multipart(), y iter_parts() cederá (yield) una lista de subpartes.

  • La mayoría de mensajes con una tipo de contenido de message/* (tal como message/delivery-status y message/rfc822) también serán analizados como objetos contenedores que contienen una lista de cargas de longitud 1. Su método is_multipart() retornará True. El único elemento cedido (yielded) por iter_parts() será un objeto sub-mensaje.

  • Algunos mensajes de conformidad no estándar pueden no ser internamente consistentes acerca de su multipart-idad. Tales mensajes pueden tener una cabecera Content-Type de tipo multipart, pero su método is_multipart() puede retornar False. Si tales mensajes son analizados con FeedParser, tendrán una instancia de la clase MultipartInvariantViolationDefect en su lista de atributos defects. Véase email.errors para más detalles.