email.generator: Generando documentos MIME

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

Una de las tareas más comunes es generar la versión plana (serializada) del mensaje de correo electrónico representado por una estructura de objeto de mensaje. Se tendrá que hacer esto si se desea enviar un mensaje a través de smtplib.SMTP.sendmail(), o el módulo nntplib, o imprimir el mensaje en la consola. Tomar una estructura de objeto de mensaje y producir una representación serializada es el trabajo de las clases generadoras.

Al igual que con el módulo email.parser, no se limita a la funcionalidad del generador incluido; se podría escribir uno desde cero. Sin embargo, el generador incluido sabe cómo generar la mayoría del correo electrónico de una manera compatible con los estándares, debería controlar los mensajes de correo electrónico MIME y no MIME bien. Está diseñado para que las operaciones de análisis y generación orientadas a bytes sean inversas, asumiendo que se utilice la misma policy de no transformación para ambos. Es decir, analizar la secuencia de bytes serializada a través de la clase BytesParser y, a continuación, regenerar la secuencia de bytes serializada mediante BytesGenerator debe producir una salida idéntica a la entrada 1. (Por otro lado, el uso del generador en un EmailMessage construido por el programa puede dar lugar a cambios en el objeto EmailMessage a medida que se rellenan los valores predeterminados.)

La clase Generator se puede utilizar para acoplar un mensaje en una representación serializada de texto (a diferencia de la binaria). Sin embargo, como Unicode no puede representar datos binarios directamente, el mensaje es necesariamente transformado en algo que contiene sólo caracteres ASCII. Se utiliza las técnicas de codificación de transferencia de contenido RFC de correo electrónico estándar para codificar mensajes de correo electrónico para el transporte a través de canales que no son «8 bits limpios».

Para adaptar procesamiento reproducible de mensajes firmados por SMIME, Generator deshabilita el encabezamiento para las partes del mensaje de tipo multipart/signed y todas sus subpartes.

class email.generator.BytesGenerator(outfp, mangle_from_=None, maxheaderlen=None, *, policy=None)

Retorna un objeto BytesGenerator que escribirá cualquier mensaje provisto por el método flatten(), o cualquier texto de escape sustituto cifrado con el método write(), al file-like object outfp. outfp debe soportar un método``write`` que acepte datos binarios.

Si mangle_from_ opcional es True, se coloca un carácter “”>”” delante de cualquier línea del cuerpo que comience con la cadena exacta ““«From «””, es decir, “”From”” seguido de un espacio al principio de una línea. mangle_from_ vuelve de forma predeterminada al valor de la configuración mangle_from_ de la norma (que es “”True”” para la norma compat32 y “”False”” para todas las demás). mangle_from_ está diseñado para su uso cuando los mensajes se almacenan en formato unix mbox (consulte mailbox y WHY THE CONTENT-LENGTH FORMAT IS BAD).

Si maxheaderlen no es None, se repliega las líneas de encabezado que son mayores que maxheaderlen, o si es 0, no se reenvuelve ningún encabezado. Si manheaderlen es None (predeterminado), se envuelven los encabezados y otras líneas de mensajes de acuerdo a los ajustes de policy.

Si la norma es especificada, se usa esa norma para controlar la generación de mensajes. Si la norma es None (predeterminado), se usa la norma asociada con el Message o el objeto EmailMessage pasado para flatten para controlar la generación del mensaje. Se puede ver email.policy para detalles de que controla la norma.

Nuevo en la versión 3.2.

Distinto en la versión 3.3: Agregada la palabra clave norma.

Distinto en la versión 3.6: El comportamiento predeterminado de los parámetros mangle_from_ y maxheaderlen es para seguir la norma.

flatten(msg, unixfrom=False, linesep=None)

Imprime la representación textual de la estructura del objeto de mensaje originada en msg al archivo de salida especificado cuando se creó la instancia BytesGenerator.

Si el tipo cte_type de la opción policy :attr:””email.policy.Policy.cte_type” es “”8bit”” (valor predeterminado), se copia los encabezados en el mensaje analizado original que no se hayan modificado con ningún bytes a la salida con el conjunto de bits altos, reproducido como en el original, y se conserva el Content-Transfer-Encoding no ASCII de cualquier parte del cuerpo que los tenga. Si cte_type es 7bit, se convierte los bytes con el conjunto de bits altos según sea necesario utilizando un Content-Transfer-Encoding compatible con ASCII . Es decir, se transforma partes con Content-Transfer-Encoding no ASCII (Content-Transfer-Encoding: 8bit) en un conjunto de caracteres compatible con ASCII Content-Transfer-Encoding, y se codifica bytes inválidos RFC no ASCII en encabezados mediante el conjunto de caracteres MIME unknown-8bit, lo que los convierte en compatibles con RFC.

Si unixfrom es True, se imprime el delimitador de encabezado de sobre utilizado por el formato de buzón de correo Unix (consulta mailbox) antes del primero de los encabezados RFC 5322 del objeto de mensaje raíz. Si el objeto raíz no tiene encabezado de sobre, se crea uno estándar. El valor predeterminado es False. Tener en cuenta que para las subpartes, nunca se imprime ningún encabezado de sobre.

Si linesep no es None, se usa como caracter separador entre todas las líneas del mensaje acoplado. Si linesep es None (predeterminado), se usa el valor especificado en la norma.

clone(fp)

Retorna un clon independiente de esta instancia de BytesGenerator con las mismas configuraciones exactas, y fp como el nuevo outfp.

write(s)

Codifica s usando el códec ASCII u el manipulador de error escape sustituto, y lo pasa al método write del outfp pasado al constructor de la clase BytesGenerator.

Como conveniencia, EmailMessage provee los métodos as_bytes() y bytes(aMessage) (también conocido como __bytes__()) que simplifican la generación de la representación serializada binaria de un objeto mensaje. Para más detalle, ver email.message.

Dado que las cadenas de caracteres no pueden representar datos binarios, la clase Generator debe convertir los datos binarios en cualquier mensaje que aplane a un formato compatible con ASCII, convirtiéndolos en un Content-Transfer_Encoding compatible con ASCII. Usando la terminología de RFC de correo electrónico, se puede pensar en esto como Generator serializando a una secuencia de E/S que no es «8 bit clean». En otras palabras, la mayoría de las aplicaciones querrán usar BytesGenerator, y no Generator.

class email.generator.Generator(outfp, mangle_from_=None, maxheaderlen=None, *, policy=None)

Retorna un objeto Generator que escribirá cualquier mensaje provisto al método flatten(), o cualquier texto provisto al método write(), al file-like object outfp. outfp debe soportar un método write que acepte datos de cadena de caracteres.

Si mangle_from_ opcional es True, se coloca un carácter “”>”” delante de cualquier línea del cuerpo que comience con la cadena exacta ““«From «””, es decir, “”From”” seguido de un espacio al principio de una línea. mangle_from_ vuelve de forma predeterminada al valor de la configuración mangle_from_ de la norma (que es “”True”” para la norma compat32 y “”False”” para todas las demás). mangle_from_ está diseñado para su uso cuando los mensajes se almacenan en formato unix mbox (consulte mailbox y WHY THE CONTENT-LENGTH FORMAT IS BAD).

Si maxheaderlen no es None, se repliega las líneas de encabezado que son mayores que maxheaderlen, o si es 0, no se reenvuelve ningún encabezado. Si manheaderlen es None (predeterminado), se envuelven los encabezados y otras líneas de mensajes de acuerdo a los ajustes de policy.

Si la norma es especificada, se usa esa norma para controlar la generación de mensajes. Si la norma es None (predeterminado), se usa la norma asociada con el Message o el objeto EmailMessage pasado para flatten para controlar la generación del mensaje. Se puede ver email.policy para detalles de que controla la norma.

Distinto en la versión 3.3: Agregada la palabra clave norma.

Distinto en la versión 3.6: El comportamiento predeterminado de los parámetros mangle_from_ y maxheaderlen es para seguir la norma.

flatten(msg, unixfrom=False, linesep=None)

Imprime la representación textual de la estructura del objeto de mensaje originado en el msg al archivo especificado de salida cuando la instancia de Generator fue creada.

Si la opción policy cte_type es 8bit, se genera el mensaje como si la opción estuviera establecida en 7bit. (Esto es necesario porque las cadenas de caracteres no pueden representar bytes que no sean ASCII). Convierte cualesquiera bytes con el conjunto de bits alto según sea necesario utilizando un Content-Transfer-Encoding compatible con ASCII. Es decir, transforma partes con Content-Transfer-Encoding (Content-Transfer-Encoding: 8bit) no ASCII en un conjunto de caracteres Content-Transfer-Encoding compatible con ASCII. Y codifica bytes no ASCII RFC inválidos ASCII en encabezados mediante el conjunto de caracteres MIME unknown-8bit, lo que los convierte en compatibles con RFC.

Si unixfrom es True, se imprime el delimitador de encabezado de sobre utilizado por el formato de buzón de correo Unix (consulta mailbox) antes del primero de los encabezados RFC 5322 del objeto de mensaje raíz. Si el objeto raíz no tiene encabezado de sobre, se crea uno estándar. El valor predeterminado es False. Tener en cuenta que para las subpartes, nunca se imprime ningún encabezado de sobre.

Si linesep no es None, se usa como caracter separador entre todas las líneas del mensaje acoplado. Si linesep es None (predeterminado), se usa el valor especificado en la norma.

Distinto en la versión 3.2: Agrega soporte para el recodificado de cuerpos de mensajes 8bit, y el argumento linesep.

clone(fp)

Retorna un clon independiente de esta instancia de Generator con las mismas opciones exactas y fp como la nueva outfp.

write(s)

Escribe s al método write del outfp pasado al constructor de la Generator. Esto provee justo la suficiente API de tipo archivo para instancias de Generator para ser usadas en la función print().

Para conveniencia, EmailMessage provee los métodos as_string() y str(aMessage) (también conocido como __str__()), que simplifican la generación de una representación de una cadena de caracteres formateada de un objeto mensaje. Para más detalles, ver email.message.

El módulo email.generator también provee una clase derivada, DecodedGenerator, la cual es como la clase base Generator, excepto que las partes no text no están serializadas, sino que en su lugar, están representadas en el flujo de salida por una cadena de caracteres derivada de una plantilla llenada con información sobre la parte.

class email.generator.DecodedGenerator(outfp, mangle_from_=None, maxheaderlen=None, fmt=None, *, policy=None)

Se actúa como Generator, excepto para cualquier subparte del mensaje pasado a Generator.flatten(), si la subparte es de tipo principal text, se imprime la carga útil decodificada de la subparte, y si el tipo principal no es text, en lugar de imprimirlo se rellena la cadena de caracteres fmt utilizando la información de la parte y se imprime la cadena de caracteres rellenada resultante.

Para llenar fmt, se ejecuta fmt % part_info, donde part_info es un diccionario compuesto por las siguientes claves y valores:

  • type – Todo el tipo MIME de la parte notext

  • maintype – Principal tipo MIME de la parte notext

  • subtype – Tipo sub-MIME de la parte no-text

  • filename – Nombre de archivo de la parte notext

  • description – Descripción asociada con la parte notext

  • encoding – Codificado de la transferencia del contenido de la parte no-text

Si fmt es None, se usa el siguiente fmt predeterminado:

«[Non-text (%(type)s) part of message omitted, filename %(filename)s]»

Los opcionales _mangle_from_ y maxheaderlen son como en la clase base Generator.

Notas al pie

1

Esta instrucción supone que se utiliza la configuración adecuada para unixfrom, y que no hay ninguna configuración policy que llame a ajustes automáticos (por ejemplo, refold_source debe ser none, que es no es el valor predeterminado). Esto tampoco es 100% verdadero, ya que si el mensaje no se ajusta a los estándares RFC ocasionalmente la información sobre el texto original exacto se pierde durante la el análisis de recuperación de errores. Es un objetivo fijar estos últimos casos extremos cuando sea posible.