This document is for an old version of Python that is no longer supported. You should upgrade and read the documentação do Python para versão estável atual.

# 18.1.9. `email.utils`: Utilitários diversos

There are several useful utilities provided in the `email.utils` module:

`email.utils.``quote`(str)

  Devolve uma nova string com barras invertidas em str substituídas por duas barras invertidas e aspas duplas substituídas por aspas duplas invertidas.

`email.utils.``unquote`(str)

  Retorna uma nova string que é uma versão sem aspas de str. Se str terminar e começar com aspas duplas, elas serão removidas. Da mesma forma, se str termina e começa com colchetes angulares, eles são removidos.

`email.utils.``parseaddr`(address)

  Analisa o endereço – que deve ser o valor de algum campo contendo endereço, como To ou Cc – em suas partes constituinte realname e email address. Retorna uma tupla daquela informação, a menos que a análise falhe, caso em que uma tupla de 2 de `('', '')` é retornada.

`email.utils.``formataddr`(pair)

  O inverso de `parseaddr()`, isto leva uma tupla de 2 do forma `(realname, email_address)` e retorna o valor de string adequado para um cabeçalho To ou Cc . Se o primeiro elemento de pair for falso, o segundo elemento será retornado sem modificações.

`email.utils.``getaddresses`(fieldvalues)

  Este método retorna uma lista de tuplas 2 do formulário retornado por `parseaddr()`. fieldvalues é uma sequência de valores do campo de cabeçalho que pode ser retornada por `Message.get_all`. Aqui está um exemplo simples que recebe todos os destinatários de uma mensagem:

      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)

`email.utils.``parsedate`(date)

  Tenta analisar uma data de acordo com as regras em RFC 2822. no entanto, alguns mailers não seguem esse formato conforme especificado, portanto `parsedate()` tenta adivinhar corretamente em tais casos. date é uma string contendo uma data RFC 2822, como `"Mon, 20 Nov 1995 19:12:08 -0500"`. Se conseguir analisar a data, `parsedate()` retorna uma 9-tupla que pode ser passada diretamente para `time.mktime()`; caso contrário, `None` será retornado. Observe que os índices 6, 7 e 8 da tupla de resultados não são utilizáveis.

`email.utils.``parsedate_tz`(date)

  Performs the same function as `parsedate()`, but returns either `None` or a 10-tuple; the first 9 elements make up a tuple that can be passed directly to `time.mktime()`, and the tenth is the offset of the date’s timezone from UTC (which is the official term for Greenwich Mean Time) 1. If the input string has no timezone, the last element of the tuple returned is `None`. Note that indexes 6, 7, and 8 of the result tuple are not usable.

`email.utils.``mktime_tz`(tuple)

  Turn a 10-tuple as returned by `parsedate_tz()` into a UTC timestamp (seconds since the Epoch). If the timezone item in the tuple is `None`, assume local time.

`email.utils.``formatdate`([timeval[, localtime][, usegmt]])

  Returns a date string as per RFC 2822, e.g.:

      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.

  Há um sinalizador opcional localtime, que, quando é `True`, interpreta timeval e retorna uma data relativa ao fuso horário local em vez do UTC, levando em consideração o horário de verão. O padrão é `False`, o que significa que o UTC é usado.

  Optional usegmt is a flag that when `True`, outputs a date string with the timezone as an ascii string `GMT`, rather than a numeric `-0000`. This is needed for some protocols (such as HTTP). This only applies when localtime is `False`. The default is `False`.

  Novo na versão 2.4.

`email.utils.``make_msgid`([idstring])

  Returns a string suitable for an RFC 2822-compliant Message-ID header. Optional idstring if given, is a string used to strengthen the uniqueness of the message id.

`email.utils.``decode_rfc2231`(s)

  Decode the string s according to RFC 2231.

`email.utils.``encode_rfc2231`(s[, charset[, language]])

  Encode the string s according to RFC 2231. Optional charset and language, if given is the character set name and language name to use. If neither is given, s is returned as-is. If charset is given but language is not, the string is encoded using the empty string for language.

`email.utils.``collapse_rfc2231_value`(value[, errors[, fallback_charset]])

  When a header parameter is encoded in RFC 2231 format, `Message.get_param` may return a 3-tuple containing the character set, language, and value. `collapse_rfc2231_value()` turns this into a unicode string. Optional errors is passed to the errors argument of the built-in `unicode()` function; it defaults to `replace`. Optional fallback_charset specifies the character set to use if the one in the RFC 2231 header is not known by Python; it defaults to `us-ascii`.

  For convenience, if the value passed to `collapse_rfc2231_value()` is not a tuple, it should be a string and it is returned unquoted.

`email.utils.``decode_params`(params)

  Decode parameters list according to RFC 2231. params is a sequence of 2-tuples containing elements of the form `(content-type, string-value)`.

Alterado na versão 2.4: The `dump_address_pair()` function has been removed; use `formataddr()` instead.

Alterado na versão 2.4: The `decode()` function has been removed; use the `Header.decode_header` method instead.

Alterado na versão 2.4: The `encode()` function has been removed; use the `Header.encode` method instead.

Notas de Rodapé

1

  Note that the sign of the timezone offset is the opposite of the sign of the `time.timezone` variable for the same timezone; the latter variable follows the POSIX standard while this module follows RFC 2822.