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