# `email.header`: Internationalized headers

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

Este módulo es parte de la API de email heredada (`Compat32`). En la API actual, la codificación y decodificación de las cabeceras se gestiona de forma transparente por la API de tipo diccionario de la clase `EmailMessage`. Además de los usos del código heredado, este módulo puede ser útil en aplicaciones que necesiten controlar completamente el conjunto de caracteres usado cuando se codifican las cabeceras.

El resto del texto de esta sección es la documentación original del módulo.

RFC 2822 es el estándar base que describe el formato de los mensajes de correo electrónico. Deriva del estándar anterior RFC 822, cuyo uso se generalizó durante una época en la que la mayoría del correo electrónico se componía únicamente de caracteres ASCII. RFC 2822 es una especificación que se escribió asumiendo que el correo electrónico contiene solo caracteres ASCII 7-bit.

Por supuesto, al haberse extendido el correo electrónico por todo el mundo, se ha internacionalizado, de forma que ahora pueden usarse los conjuntos de caracteres específicos de un idioma en los mensajes de correo electrónico. El estándar base todavía requiere que los mensajes de correo electrónico sean transferidos usando solo caracteres ASCII 7-bit, así que se han escrito multitud de RFCs describiendo cómo codificar correos electrónicos que contengan caracteres no ASCII en formatos conforme a la RFC 2822. Entre estas RFCs se incluyen RFC 2045, RFC 2046, RFC 2047 y RFC 2231. El paquete `email` soporta estos estándares en sus módulos `email.header` y `email.charset`.

Si quieres incluir caracteres no ASCII en tus cabeceras de correo electrónico, por ejemplo en los campos Subject o To, deberías usar la clase `Header` y asignar el campo del objeto `Message` a una instancia de `Header` en vez de usar una cadena de caracteres para el valor de la cabecera. Importa la clase `Header` del módulo `email.header`. Por ejemplo:

    >>> from email.message import Message
    >>> from email.header import Header
    >>> msg = Message()
    >>> h = Header('p\xf6stal', 'iso-8859-1')
    >>> msg['Subject'] = h
    >>> msg.as_string()
    'Subject: =?iso-8859-1?q?p=F6stal?=\n\n'

¿Has visto cómo hemos hecho que el campo Subject contuviera un caracter no ASCII? Lo hemos hecho creando una instancia de `Header` y pasándole el conjunto de caracteres en los que estaba codificado la cadena de bytes. Cuando la instancia de `Message` subsecuente se ha aplanado, el campo Subject se ha codificado en RFC 2047 adecuadamente. Los lectores de correo que soportan MIME deberían mostrar esta cabecera usando el caracter ISO-8859-1 incrustado.

Aquí está la descripción de la clase `Header`:

class email.header.Header(s=None, charset=None, maxlinelen=None, header_name=None, continuation_ws=' ', errors='strict')

  Crea una cabecera conforme a las especificaciones MIME que contiene cadenas de caracteres en diferentes conjuntos de caracteres.

  El argumento opcional s es el valor inicial de la cabecera. Si es `None` (el valor por defecto), el valor inicial de la cabecera quedará sin asignar. Puedes añadirlo luego a la cabecera con llamadas al método `append()`. s debe ser una instancia de `bytes` o `str`, pero lee la documentación de `append()` para conocer los detalles semánticos.

  El argumento opcional charset sirve para dos propósitos: tiene el mismo significado que el argumento charset en el método `append()`. También asigna el conjunto de caracteres por defecto para todas las llamadas subsecuentes a `append()` que omitan el argumento charset. Si no se proporciona charset en el constructor (por defecto), el conjunto de caracteres `us-ascii` se usa tanto para el conjunto de caracteres inicial de s como por defecto para las llamadas subsecuentes a `append()`.

  The maximum line length can be specified explicitly via maxlinelen. For splitting the first line to a shorter value (to account for the field header which isn’t included in s, e.g. Subject) pass in the name of the field in header_name. The default maxlinelen is 78, and the default value for header_name is `None`, meaning it is not taken into account for the first line of a long, split header.

  El argumento opcional continuation_ws debe ser conforme a las normas de espacios en blanco plegables de la RFC 2822, y normalmente es o un espacio o un caracter tabulador. Este caracter se antepondrá delante de las líneas continuadas. El valor por defecto de continuation_ws es un solo espacio.

  El argumento opcional errors se pasa directamente a través del método `append()`.

  append(s, charset=None, errors='strict')

    Añade la cadena de caracteres s a la cabecera MIME.

    El argumento opcional charset, si se proporciona, debe ser una instancia de `Charset` (ver `email.charset`) o el nombre de un conjunto de datos, que deberá ser convertido a una instancia de `Charset`. Un valor de `None` (el valor por defecto) significa que se usará el charset dado en el constructor.

    s puede ser una instancia de `bytes` o de `str`. Si es una instancia de `bytes`, entonces charset es la codificación de esa cadena de bytes, y se lanzará un `UnicodeError` si la cadena de caracteres no puede decodificarse con ese conjunto de caracteres.

    Si s es una instancia de `str`, entonces charset es una sugerencia que especifica el conjunto de caracteres usando en la cadena de caracteres.

    En cualquier caso, cuando se produce una cabecera conforme a la RFC 2822 usando las reglas de la RFC 2047, la cadena de caracteres se codificará usando el códec de salida del conjunto de caracteres. Si la cadena de caracteres no puede codificarse usando el códec de salida, se lanzará un UnicodeError.

    El argumento opcional errors se pasa como el argumento de errores para la llamada de decodificación si s es una cadena de bits.

  encode(splitchars=';, \t', maxlinelen=None, linesep='\n')

    Codifica un mensaje de la cabecera en un formato conforme a RFC, posiblemente envolviendo las líneas largas y encapsulando las partes no ASCII en base64 o en codificaciones imprimibles entrecomilladas.

    El argumento opcional splitchars es una cadena de caracteres que contiene caracteres a los que el algoritmo de separación debería asignar espacio extra durante la encapsulación de la cabecera normal. Esto da un basto soporte a los saltos sintácticos de alto nivel de la RFC 2822: los puntos de separación precedidos por un caracter separador tienen preferencia durante la separación de la línea, con preferencia de caracteres en el orden en el que aparecen en la cadena de caracteres. El espacio y el tabulador pueden incluirse en la cadena de caracteres para indicar si se debería dar preferencia a uno sobre el otro como punto de separación cuando no aparezcan otros caracteres separadores en la línea que se está dividiendo. Los caracteres separadores no afectan a las líneas codificadas de la RFC 2047.

    maxlinelen, si se proporciona, sobrescribe el valor de longitud de línea máxima para la instancia.

    linesep especifica los caracteres usados para separar las líneas de la cabecera plegada. Su valor por defecto es el valor más útil para el código de una aplicación Python (`\n`), pero se puede especificar `\r\n` para producir cabeceras con separadores de línea conforme a RFCs.

    Distinto en la versión 3.2: Argumento linesep añadido.

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

  __str__()

    Retorna una aproximación de `Header` como una cadena de caracteres, usando una longitud de línea ilimitada. Todas las piezas se convierten a unicode utilizando la codificación especificada y unidas adecuadamente. Todas las piezas con un conjunto de caracteres `'unknown-8bit'` se decodifican como ASCII usando el gestor de errores de `'replace'`.

    Distinto en la versión 3.2: Añadida gestión del conjunto de caracteres `'unknown-8bit'`.

  __eq__(other)

    Este método permite comparar si dos instancias de `Header` son iguales.

  __ne__(other)

    Este método permite comparar si dos instancias de `Header` no son iguales.

El módulo `email.header` También proporciona las prácticas funciones que se indican a continuación.

email.header.decode_header(header)

  Decodifica el valor de un mensaje de la cabecera sin convertir el conjunto de caracteres. El valor de la cabecera está en header.

  For historical reasons, this function may return either:

  1. A list of pairs containing each of the decoded parts of the header, `(decoded_bytes, charset)`, where decoded_bytes is always an instance of `bytes`, and charset is either:

     > - A lower case string containing the name of the character set specified.

     > - `None` for non-encoded parts of the header.

  2. A list of length 1 containing a pair `(string, None)`, where string is always an instance of `str`.

  An `email.errors.HeaderParseError` may be raised when certain decoding errors occur (e.g. a base64 decoding exception).

  Here are examples:

      >>> from email.header import decode_header
      >>> decode_header('=?iso-8859-1?q?p=F6stal?=')
      [(b'p\xf6stal', 'iso-8859-1')]
      >>> decode_header('unencoded_string')
      [('unencoded_string', None)]
      >>> decode_header('bar =?utf-8?B?ZsOzbw==?=')
      [(b'bar ', None), (b'f\xc3\xb3o', 'utf-8')]

  Nota

  This function exists for backwards compatibility only. For new code, we recommend using `email.headerregistry.HeaderRegistry`.

email.header.make_header(decoded_seq, maxlinelen=None, header_name=None, continuation_ws=' ')

  Crea una instancia de `Header` a partir de una secuencia de duplas como las retornadas por `decode_header()`.

  `decode_header()` toma el valor de una cadena de caracteres de la cabecera y retorna una secuencia de duplas con el formato `(decoded_string, charset)`, donde charset es el nombre del conjunto de caracteres.

  Esta función toma una de esas secuencias de duplas y retorna una instancia de `Header`. Los argumentos opcionales maxlinelen, header_name y continuation_ws son como los del constructor `Header`.

  Nota

  This function exists for backwards compatibility only, and is not recommended for use in new code.