"email.utils": Miscellaneous utilities
**************************************

**Código fuente:** Lib/email/utils.py

======================================================================

There are a couple of useful utilities provided in the "email.utils"
module:

email.utils.localtime(dt=None)

   Return local time as an aware datetime object.  If called without
   arguments, return current time.  Otherwise *dt* argument should be
   a "datetime" instance, and it is converted to the local time zone
   according to the system time zone database.  If *dt* is naive (that
   is, "dt.tzinfo" is "None"), it is assumed to be in local time.

   Added in version 3.3.

   Deprecated since version 3.12, removed in version 3.14: El
   parámetro *isdst*.

email.utils.make_msgid(idstring=None, domain=None)

   Retorna una cadena de caracteres apropiada para una cabecera
   *Message-ID*  que cumpla con **RFC 2822**. Si se especifica un
   *idstring* opcional, es una cadena de caracteres utilizada para
   reforzar la unicidad del identificador del mensaje. Si se
   especifica un *domain* opcional provee la porción del msgid después
   de '@'. El predeterminado es el hostname local. Normalmente no es
   necesario especificar este valor, pero puede ser útil en algunos
   casos, como cuando se está construyendo un sistema distribuido que
   utiliza un nombre de dominio consistente a lo largo de varios
   ordenadores.

   Distinto en la versión 3.2: Se añadió la palabra clave *domain*.

Las funciones que quedan son parte de la API de correo electrónico
heredada ("Compat32") . No hay necesidad de utilizarlas directamente
con el nuevo API, dado que el análisis sintáctico y formateo que
proporcionan es realizado automáticamente por el mecanismo de análisis
sintáctico de la nueva API.

email.utils.quote(str)

   Retorna una nueva cadena de caracteres con barras invertidas ("\")
   en *str* reemplazado por dos barras invertidas, y comillas dobles
   reemplazadas por barra invertida seguido de comillas dobles.

email.utils.unquote(str)

   Retorna una nueva cadena de caracteres que es una versión
   *unquoted* de *str*. Si *str* comienza y termina con comillas
   dobles, éstas son eliminadas. De igual manera si *str* empieza y
   termina con comillas angulares ("<" y ">"), éstas son eliminadas.

email.utils.parseaddr(address, *, strict=True)

   Interpreta *address* -- la cual debe ser el valor de un campo que
   contenga un campo tal como *To* o *Cc* -- para separarlo en sus
   componentes *realname* y *email address*. Retorna una tupla de
   información, a menos que la interpretación falle, en cuyo caso una
   2-tupla de "('','')" es retornada.

   If *strict* is true, use a strict parser which rejects malformed
   inputs.

   Distinto en la versión 3.13: Add *strict* optional parameter and
   reject malformed inputs by default.

email.utils.formataddr(pair, charset='utf-8')

   El inverso de "parseaddr()", este toma una 2-tupla de la forma
   "(realname,real, email_address)" y retorna una cadena de caracteres
   válido para una cabecera *To* o *Cc*. Si el primer elemento de
   *pair* es falso, entonces el segundo elemento es retornado sin
   modificación.

   El *charset* opcional es el conjunto de caracteres que será usado
   en la codificación **RFC 2047** del "real_name" si el "real_name"
   contiene caracteres que no sean ASCII. Puede ser una instancia de
   "str" o "Charset". El valor predeterminado es "utf-8".

   Distinto en la versión 3.3: Se añadió la opción *charset*.

email.utils.getaddresses(fieldvalues, *, strict=True)

   This method returns a list of 2-tuples of the form returned by
   "parseaddr()". *fieldvalues* is a sequence of header field values
   as might be returned by "Message.get_all".

   If *strict* is true, use a strict parser which rejects malformed
   inputs.

   Here's a simple example that gets all the recipients of a message:

      from email.utils import getaddresses

      tos = msg.get_all('to', [])
      ccs = msg.get_all('cc', [])
      resent_tos = msg.get_all('resent-to', [])
      resent_ccs = msg.get_all('resent-cc', [])
      all_recipients = getaddresses(tos + ccs + resent_tos + resent_ccs)

   Distinto en la versión 3.13: Add *strict* optional parameter and
   reject malformed inputs by default.

email.utils.parsedate(date)

   Intenta interpretar una fecha de acuerdo a las reglas en **RFC
   2822**. Sin embargo, algunos clientes de correo no siguen ese
   formato como está especificado, por lo cual "parsedate()" intenta
   adivinar correctamente en esos casos. *date* es una secuencia de
   caracteres que contiene una fecha **RFC 2822** como ""Mon, 20 Nov
   1995 19:12:08 -0500"". Si tiene éxito en interpretar la fecha,
   "parsedate()" retorna una 9-tupla que puede ser pasada directamente
   a "time.mktime()"; de lo contrario "None" es retornado. Observar
   que los índices 6,7 y 8 de la tupla resultante no son utilizables.

email.utils.parsedate_tz(date)

   Realiza la misma función que "parsedate()", pero retorna "None" o
   una 10-tupla; los primeros 9 elementos forman una tupla que puede
   ser pasada directamente a "time.mktime()", y el décimo es el
   desfase de la zona horaria de la fecha con respecto a UTC (que es
   el término oficial para Greenwich Mean Time) [1]. Si la cadena de
   caracteres de entrada no tiene zona horaria, el último elemento de
   la tupla retornada es "0", el cual representa UTC. Nótese que los
   índices 6, 7 y 8 de la tupla resultante no son utilizables.

email.utils.parsedate_to_datetime(date)

   Lo inverso de "format_datetime()". Realiza la misma función que
   "parsedate()", pero en caso de éxito retorna un "datetime"; de lo
   contrario, "ValueError" se lanza si *date* contiene un valor no
   válido, como una hora superior a 23 o una diferencia de zona
   horaria no comprendida entre -24 y 24 horas. Si la fecha de entrada
   tiene una zona horaria de "-0000", el "datetime" será un "datetime"
   ingenuo, y si la fecha se ajusta a las RFC, representará una hora
   en UTC pero sin indicación de la zona horaria de origen real del
   mensaje de donde proviene la fecha. . Si la fecha de entrada tiene
   cualquier otra compensación de zona horaria válida, el "datetime"
   será un "datetime" consciente con el correspondiente "timezone"
   "tzinfo".

   Added in version 3.3.

email.utils.mktime_tz(tuple)

   Cambia una 10-tupla, como la retornada por "parsedate_tz()" a una
   marca de tiempo UTC (segundos desde la Época). Si la zona horaria
   en la tupla es "None", asume el tiempo local.

email.utils.formatdate(timeval=None, localtime=False, usegmt=False)

   Retorna una fecha como una cadena de caracteres de acuerdo a **RFC
   2822**, por ejemplo:

      Fri, 09 Nov 2001 01:08:47 -0000

   Optional *timeval* if given is a floating-point time value as
   accepted by "time.gmtime()" and "time.localtime()", otherwise the
   current time is used.

   *localtime* opcional, es una bandera que cuando es "True",
   interpreta *timeval* y retorna una fecha relativa a la zona horaria
   local en lugar de UTC, tomando apropiadamente en cuenta el horario
   de verano. El valor predeterminado es "False" con lo cual UTC es
   utilizado.

   *usegmt* opcional, es una bandera que cuando es "True" retorna una
   fecha como cadena de caracteres con la zona horaria como una cadena
   de caracteres ascii "GMT", en lugar de un numérico "-0000". Esto es
   necesario para algunos protocolos (como HTTP). Sólo aplica cuando
   *localtime* es "False". El valor predeterminado es "False".

email.utils.format_datetime(dt, usegmt=False)

   Similar a "formatdate", pero la entrada es una instancia
   "datetime". Si es un datetime naíf, se asume ser "UTC sin
   información sobre la zona horaria de origen", y el "-0000"
   convencional es usado para la zona horaria. Si es un "datetime"
   consciente entonces el desfase numérico de la zona horaria es
   utilizado. Si es una zona horaria consciente con un desfase cero,
   entonces *usegmt* puede ser "True", en cuyo caso la cadena de
   caracteres "GMT" es utilizada en lugar del desfase numérico de zona
   horaria. Esto provee una manera de generar cabeceras de fecha HTTP
   conforme estándares.

   Added in version 3.3.

email.utils.decode_rfc2231(s)

   Decodifica la cadena de caracteres *s* de acuerdo a **RFC 2231**.

email.utils.encode_rfc2231(s, charset=None, language=None)

   Codifica la cadena de caracteres *s* de acuerdo a **RFC 2231**.
   *charset* y *language* opcionales, si son dados es el conjunto de
   caracteres y nombre del lenguaje a utilizar. Si ninguno es dado,
   *s* es retornado sin modificar. Si *charset* es dado pero
   *language* no, la cadena de caracteres es codificada usando la
   cadena de  caracteres vacía para *language*.

email.utils.collapse_rfc2231_value(value, errors='replace', fallback_charset='us-ascii')

   Cuando un parámetro de cabecera está codificado en formato **RFC
   2231**, "Message.get_param" puede retornar una 3-tupla conteniendo
   el conjunto de caracteres, lenguaje y valor.
   "collapse_rfc2231_value()" convierte esto en una cadena de
   caracteres unicode. El parámetro opcional *errors* es pasado al
   argumento *errors* del método "encode()" de "str"; de manera
   predeterminada recae en "'replace'". *fallback_charset* opcional,
   especifica el conjunto de caracteres a utilizar si el especificado
   en la cabecera **RFC 2231** no es conocido por Python; su valor
   predeterminado es "'us-ascii'".

   Por conveniencia, si el *value* pasado a "collapse_rfc2231_value()"
   no es una tupla, debería ser una cadena de caracteres y se retorna
   sin citar.

email.utils.decode_params(params)

   Decodifica la lista de parámetros de acuerdo a **RFC 2231**.
   *params* es una secuencia de 2-tuplas conteniendo elementos de la
   forma "(content-type, string-value)".

-[ Notas a pie de página ]-

[1] Nótese que el signo del desfase de la zona horaria es opuesto al
    signo de la variable "time.timezone" para la misma zona horaria;
    este último sigue el estándar POSIX mientras que este módulo sigue
    **RFC 2822**.
