# `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)

  Works like `BytesFeedParser` except that the input to the `feed()` method must be a string. This is of limited utility, since the only way for such a message to be valid is for it to contain only ASCII text or, if `utf8` is `True`, no binary attachments.

  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()`.

    The bytes contained in fp must be formatted as a block of RFC 5322 (or, if `utf8` is `True`, RFC 6532) style headers and header continuation lines, optionally preceded by an envelope header. The header block is terminated either by the end of the data or by a blank line. Following the header block is the body of the message (which may contain MIME-encoded subparts, including subparts with a Content-Transfer-Encoding of `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.