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 nome 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)

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

email.utils.formataddr(pair)

O inverso de: meth: parseaddr, isto leva uma 2-tupla do formulário (realname, email_address) e retorna o valor de string adequado para um cabeçalho: mailheader:To ou: mailheader: 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 2 tuplas do formulário retornado por parseaddr (). * fieldvalues * é uma sequência de valores do campo de cabeçalho que pode ser retornada por:meth: Message.get_all <email.message.Message.get_all>. Aqui está um exemplo simples que recebe todos os destinatários de uma 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)

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, :func:`parsedate` retorna uma 9-tupla que pode ser passada diretamente para :func:`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.