email.contentmanager: Managing MIME Content

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

Added in version 3.6: [1]

class email.contentmanager.ContentManager

Clase base para gestores de contenido. Proporciona los mecanismos de registro estándar para registrar convertidores entre contenido MIME y otras representaciones, así como los métodos de envío get_content y set_content.

get_content(msg, *args, **kw)

Busca una función de controlador basada en el mimetype de msg (ver el siguiente párrafo), la llama, le pasa todos los argumentos y retorna el resultado de la llamada. La expectativa es que el controlador extraiga la carga útil de msg y retorne un objeto que codifica información sobre los datos extraídos.

Para encontrar el controlador, busca las siguientes llaves en el registro, deteniéndose con la primera que encuentre:

  • la cadena que representa el tipo MIME completo (maintype/subtype)

  • la cadena de caracteres que representa el maintype

  • la cadena de caracteres vacía

Si ninguna de estas llaves produce un controlador, se lanza una excepción KeyError para el tipo MIME completo.

set_content(msg, obj, *args, **kw)

Si el maintype es multipart, se lanza un TypeError; de lo contrario, busca una función de controlador basada en el tipo de obj (ver el siguiente párrafo), llama a clear_content() en el msg y llama a la función de controlador, pasando todos los argumentos. La expectativa es que el controlador transforme y almacene obj en msg, posiblemente realizando otros cambios a msg también, como agregar varios encabezados MIME para codificar la información necesaria para interpretar los datos almacenados.

Para encontrar el controlador, obtiene el tipo de obj (typ = type(obj)), y busca las siguientes llaves en el registro, deteniéndose con la primera encontrada:

  • el tipo en sí (typ)

  • el nombre completo de calificación del tipo (typ.__module__ + '.' + typ.__qualname__).

  • the type’s qualname (typ.__qualname__)

  • the type’s name (typ.__name__).

If none of the above match, repeat all of the checks above for each of the types in the MRO (typ.__mro__). Finally, if no other key yields a handler, check for a handler for the key None. If there is no handler for None, raise a KeyError for the fully qualified name of the type.

También agrega un encabezado MIME-Version si no hay uno presente (vea también MIMEPart).

add_get_handler(key, handler)

Registra el handler de funciones como el manejador de key. Para los posibles valores de key, consulte get_content().

add_set_handler(typekey, handler)

Registra el handler como la función a llamar cuando un objeto de un tipo coincidente typekey se pasa a set_content(). Para los posibles valores de typekey, consulte set_content().

Instancias gestoras de contenido

Actualmente, el paquete de correo electrónico solo proporciona un administrador de contenido concreto, raw_data_manager, aunque en el futuro se pueden agregar más. raw_data_manager es el content_manager proporcionado por EmailPolicy y sus derivados.

email.contentmanager.raw_data_manager

This content manager provides only a minimum interface beyond that provided by Message itself: it deals only with text, raw bytes, and Message objects. Nevertheless, it provides significant advantages compared to the base API: get_content on a text part will return a string without the application needing to manually decode it, set_content provides a rich set of options for controlling the headers added to a part and controlling the content transfer encoding, and it enables the use of the various add_ methods, thereby simplifying the creation of multipart messages.

email.contentmanager.get_content(msg, errors='replace')

Return the payload of the part as either a string (for text parts), an EmailMessage object (for message/rfc822 parts), or a bytes object (for all other non-multipart types). Raise a KeyError if called on a multipart. If the part is a text part and errors is specified, use it as the error handler when decoding the payload to a string. The default error handler is replace.

email.contentmanager.set_content(msg, <'str'>, subtype="plain", charset='utf-8', cte=None, disposition=None, filename=None, cid=None, params=None, headers=None)
email.contentmanager.set_content(msg, <'bytes'>, maintype, subtype, cte="base64", disposition=None, filename=None, cid=None, params=None, headers=None)
email.contentmanager.set_content(msg, <'EmailMessage'>, cte=None, disposition=None, filename=None, cid=None, params=None, headers=None)

Añade cabeceras y carga útil al msg:

Añade un encabezado Content-Type con un valor maintype/subtype.

  • Para str, establece el maintype de MIME en text, y establece el subtipo en subtype si se especifica, o plain si no está presente.

  • Para bytes, usa el maintype y subtype especificados, o lanza un TypeError si no se especifican.

  • Para objetos EmailMessage, establece el maintype en message, y establece el subtype en subtype si se especifica o rfc822 si no se especifica. Si subtype es partial, se lanza un error (los objetos de bytes deben usarse para construir partes message/partial).

Si se proporciona charset (lo cual solo es válido para str), codifica la cadena de caracteres en bytes utilizando el conjunto de caracteres especificado. El valor por defecto es utf-8. Si el charset especificado es un alias conocido del nombre de un conjunto de caracteres del estándar MIME, utiliza el conjunto de caracteres estándar en su lugar.

Si se establece cte, codifica la carga útil mediante la codificación de transferencia de contenido especificada y establece el encabezado Content-Transfer-Encoding en ese valor. Los valores posibles para cte son quoted-printable, base64, 7bit, 8bit, y binary. Si la entrada no se puede codificar en la codificación especificada (por ejemplo, especificando un cte de 7bit para una entrada que contiene valores no ASCII), se lanza un ValueError.

  • For str objects, if cte is not set use heuristics to determine the most compact encoding. Prior to encoding, str.splitlines() is used to normalize all line boundaries, ensuring that each line of the payload is terminated by the current policy’s linesep property (even if the original string did not end with one).

  • For bytes objects, cte is taken to be base64 if not set, and the aforementioned newline translation is not performed.

  • Para EmailMessage, según RFC 2046, se lanza un error si se solicita un cte de quoted-printable o base64 para el subtype rfc822, y para cualquier cte que no sea 7bit para el subtype external-body. Para message/rfc822, se usa 8bit si no se especifica cte. Para todos los demás valores de subtype, se usa 7bit.

Nota

Un cte de binary todavía no funciona correctamente. El objeto EmailMessage modificado por set_content es correcto, pero BytesGenerator no lo serializa correctamente.

Si se establece disposición, se usa como valor del encabezado Content-Disposition. Si no se especifica y se especifica filename, agrega el encabezado con el valor attachment. Si no se especifica disposition y tampoco se especifica filename, no agrega el encabezado. Los únicos valores válidos para disposition son attachment e inline.

Si se especifica el filename, se usa como el valor del parámetro filename del encabezado Content-Disposition.

Si se especifica cid, agrega un encabezado Content-ID con valor cid.

Si se especifica params, itera su método items y use los pares resultantes (key, value) para establecer parámetros adicionales en el encabezado Content-Type.

Si se especifica headers y es una lista de cadenas de caracteres de la forma headername: headervalue o una lista de objetos header (que se distinguen de las cadenas de caracteres por tener un atributo name), agrega los encabezados a msg.

Notas al pie de página