email.charset: Representa conjunto de caracteres

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

Este módulo es parte de la API de email heredada (Compat32). En la nueva API solo se usa la tabla de alias.

El texto restante de esta sección corresponde a la documentación original del módulo.

Este módulo proporciona una clase Charset para representar conjuntos de caracteres y conversiones de conjuntos de caracteres en mensajes de correo electrónico, así como un registro de conjuntos de caracteres y varios métodos de conveniencia para manipular este registro. Las instancias de Charset se utilizan en varios otros módulos dentro del paquete email.

Importe esta clase desde el módulo email.charset.

class email.charset.Charset(input_charset=DEFAULT_CHARSET)

Asigna conjuntos de caracteres a sus propiedades de correo electrónico.

Esta clase proporciona información sobre los requisitos impuestos al correo electrónico para un conjunto de caracteres específico. También proporciona rutinas de conveniencia para convertir entre juegos de caracteres, dada la disponibilidad de los códecs aplicables. Dado un conjunto de caracteres, hará todo lo posible para proporcionar información sobre cómo utilizar ese conjunto de caracteres en un mensaje de correo electrónico de forma compatible con RFC.

Ciertos conjuntos de caracteres deben codificarse con quoted-printable o base64 cuando se usan en encabezados o cuerpos de correo electrónico. Ciertos conjuntos de caracteres deben convertirse directamente y no están permitidos en el correo electrónico.

Opcional input_charset es como se describe a continuación; siempre se convierte a minúsculas. Después de que el alias sea normalizado también se utiliza como una búsqueda en el registro de conjuntos de caracteres para averiguar la codificación del encabezado, codificación de cuerpo, y códec de conversión de salida que se usarán para el conjunto de caracteres. Por ejemplo, si input_charset es iso-8859-1, los encabezados y cuerpos se codificarán mediante quoted-printable y no es necesario ningún códec de conversión de salida. Si input_charset es euc-jp, los encabezados se codificarán con base64, los cuerpos no se codificarán, pero el texto de salida se convertirá del conjunto de caracteres euc-jp al conjunto de caracteres iso-2022-jp.

Las instancias Charset tienen los siguientes atributos de datos:

input_charset

El conjunto de caracteres inicial especificado. Los alias comunes se convierten a sus nombres de correo electrónico Official (por ejemplo, latin_1 se convierte a `` iso-8859-1``). El valor predeterminado es `` us-ascii “” de 7 bits.

header_encoding

Si el conjunto de caracteres debe codificarse antes de que pueda usarse en un encabezado de correo electrónico, este atributo se establecerá a Charset.QP (para quoted-printable), Charset.BASE64 (para codificación base64), o Charset.SHORTEST para la más codificación más corta QP o BASE64. De lo contrario será None.

body_encoding

Igual que header_encoding, pero describe la codificación del cuerpo del mensaje de correo, que de hecho puede ser diferente a la codificación del encabezado. Charset.SHORTEST` no está permitido para body_encoding.

output_charset

Some character sets must be converted before they can be used in email headers or bodies. If the input_charset is one of them, this attribute will contain the name of the character set output will be converted to. Otherwise, it will be None.

input_codec

El nombre del códec de Python usado para convertir el input_charset a Unicode. Si no es necesario un códec de conversión, este atributo será None.

output_codec

El nombre del códec de Python usado para convertir Unicode a output_charset. Si no es necesario un códec de conversión, este atributo tendrá el mismo valor que input_codec.

Las instancias Charset además tienen los siguientes métodos:

get_body_encoding()

Retorna la codificación de transferencia de contenido usada para la codificación del cuerpo.

This is either the string quoted-printable or base64 depending on the encoding used, or it is a function, in which case you should call the function with a single argument, the Message object being encoded. The function should then set the Content-Transfer-Encoding header itself to whatever is appropriate.

Retorna la cadena quoted-printable si body_encoding es QP, retorna la cadena base64 si body_encoding es BASE64, y retorna la cadena 7bit en caso contrario.

get_output_charset()

Return the output character set.

Este es el atributo output_charset si no es None, en caso contrario es input_charset.

header_encode(string)

Header-encode the string string.

El tipo de codificación (base64 o quoted-printable) se basará en el atributo header_encoding.

header_encode_lines(string, maxlengths)

Codifica como encabezado string convirtiéndolo primero a bytes.

Es similar a header_encode() excepto que la cadena se ajusta a las longitudes máximas indicadas en el argumento maxlengths, el cual debe ser un iterador: cada elemento retornado por este iterador proporcionará la siguiente longitud máxima de línea.

body_encode(string)

Codifica como Cuerpo la cadena string.

El tipo de codificación (base64 o quoted-printable) se basará en el atributo body_encoding.

La clase Charset también proporciona una serie de métodos para soportar operaciones estándar y funciones integradas.

__str__()

Returns input_charset as a string coerced to lower case. __repr__() is an alias for __str__().

__eq__(other)

Este método le permite comparar dos instancias Charset por igualdad.

__ne__(other)

Este método le permite comparar dos instancias Charset por desigualdad.

El módulo email.charset provee además las siguientes funciones para agregar nuevas entradas al conjunto global de caracteres, alias y registros de códecs:

email.charset.add_charset(charset, header_enc=None, body_enc=None, output_charset=None)

Añade propiedades de carácter al registro global.

charset es el conjunto de caracteres de entrada, y debe ser el nombre canónico del conjunto de caracteres.

Optional header_enc and body_enc is either Charset.QP for quoted-printable, Charset.BASE64 for base64 encoding, Charset.SHORTEST for the shortest of quoted-printable or base64 encoding, or None for no encoding. SHORTEST is only valid for header_enc. The default is None for no encoding.

Opcional output_charset es es el conjunto de caracteres en el que debe estar la salida. Las conversiones proceden del conjunto de caracteres de entrada, a Unicode, al conjunto de caracteres de salida cuando se llama al método Charset.convert(). El valor predeterminado es la salida en el mismo conjunto de caracteres que la entrada.

Tanto input_charset y output_charset deben tener entradas de códec Unicode en el conjunto de caracteres del módulo para la asignación del códec; use add_codec() para agregar códecs que el módulo no conozca. Consulte la documentación del módulo codecs para más información.

The global character set registry is kept in the module global dictionary CHARSETS.

email.charset.add_alias(alias, canonical)

Añade un alias al conjunto de caracteres. alias es el nombre del alias, p. ej. latin-1`. canonical es el nombre canónico del conjunto de caracteres, p. ej. iso-8859-1.

The global charset alias registry is kept in the module global dictionary ALIASES.

email.charset.add_codec(charset, codecname)

Add a codec that map characters in the given character set to and from Unicode.

charset es el nombre canónico de un conjunto de caracteres. codename es el nombre de un códec de Python, según corresponda para el segundo argumento del método str de encode().