19.1.14. email.utils: Utilitários diversos

Código Fonte: Lib/email/utils.py

Existem alguns utilitários úteis fornecidos no email.utils module:

email.utils.localtime(dt=None)

Retorna a hora local como um objeto datetime com reconhecimento. Se chamado sem argumentos, retorne a hora atual. Caso contrário, o argumento dt deve ser uma instância: ‘class’: ~datetime.datetime e é convertido para o fuso horário local de acordo com o banco de dados de fuso horário do sistema. Se dt é ingênuo (isto é, dt.tzinfo é None), presume-se que seja na hora local. Neste caso, um valor positivo ou zero para * isdst * faz com que `` localtime`` presuma inicialmente que o horário de verão (por exemplo, horário de verão) esteja ou não (respectivamente) em vigor pelo tempo especificado. Um valor negativo para isdst faz com que o localtime tente adivinhar se o horário de verão está em vigor pelo tempo especificado.

Novo na versão 3.3.

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

Retorna uma string adequada para um cabeçalho: rfc: 2822 -compliant: mailheader:` Message-ID`. O opcional * idstring *, se fornecido, é uma string usada para fortalecer a exclusividade do ID da mensagem. Opcional * domínio * se dado fornece a porção do msgid após o ‘@’. O padrão é o nome do host local. Normalmente, não é necessário substituir esse padrão, mas pode ser útil em alguns casos, como um sistema distribuído de construção que usa um nome de domínio consistente em vários hosts.

Alterado na versão 3.2: Adicionado a palavra-chave * domain *.

As funções restantes fazem parte da API de e-mail herdada (Compat32). Não há necessidade de usá-las diretamente com a nova API, pois a análise e a formatação fornecidas são feitas automaticamente pelo mecanismo de análise de cabeçalhos da nova API.

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, charset='utf-8')

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.

Opcional charset é o conjunto de caracteres que será usado na codificação RFC 2047 do` realname` se o``realname`` contiver caracteres não-ASCII. Pode ser uma instância de: classe: str ou a: class:` ~ email.charset.Charset`. O padrão é utf-8.

Alterado na versão 3.3: Adicionado a opção charset.

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.parsedate_to_datetime(date)

O inverso de format_datetime(). Desempenha a mesma função que parsedate(), mas em caso de sucesso retorna um datetime. Se a data de entrada tem um fuso horário de -0000, o datetime será um datetime ingênuo, e se a data estiver em conformidade com os RFCs representará um horário em UTC, mas sem indicação do fuso horário de origem real da mensagem de onde vem a data. Se a data de entrada tiver qualquer outro deslocamento de fuso horário válido, o datetime será um datetime consciente com o correspondente a timezone tzinfo.

Novo na versão 3.3.

email.utils.mktime_tz(tuple)

Transforma uma tupla de 10 conforme retornado por parsedate_tz() em um timestamp UTC (segundos desde a Era Unix). Se o item de fuso horário na tupla for None, considera a hora local.

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

Retorna uma string de data conforme RFC 2822. Por exemplo:

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

O timeval opcional, se fornecido, é um valor de tempo de ponto flutuante, conforme aceito por time.gmtime() e time.localtime(), caso contrário, o tempo atual é usado.

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.

O usegmt opcional é um sinalizador que quando True, produz uma string de data com o fuso horário como uma string ascii GMT, ao invés de um numérico -0000. Isso é necessário para alguns protocolos (como HTTP). Isso se aplica apenas quando localtime for False. O padrão é False.

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

Como formatdate, mas a entrada é uma instância de datetime. Se for uma data e hora ingênua, será considerado “UTC sem informações sobre o fuso horário de origem” e o convencional -0000 será usado para o fuso horário. Se for um datetime ciente, então o deslocamento de fuso horário numérico é usado. Se for um fuso horário ciente com deslocamento zero, então usegmt pode ser definido como True, caso em que a string GMT é usada em vez do deslocamento numérico do fuso horário. Isso fornece uma maneira de gerar cabeçalhos de data HTTP em conformidade com os padrões.

Novo na versão 3.3.

email.utils.decode_rfc2231(s)

Decodifica a string s de acordo com RFC 2231.

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

Codifica a string s de acordo com RFC 2231. charset e language opcionais, se fornecido, são o nome do conjunto de caracteres e o nome do idioma a ser usado. Se nenhum deles for fornecido, s é retornado como está. Se charset for fornecido, mas language não, a string será codificada usando a string vazia para language.

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

Quando um parâmetro de cabeçalho é codificado no formato RFC 2231, Message.get_param pode retornar uma tupla de 3 contendo o conjunto de caracteres, idioma e valor. collapse_rfc2231_value() transforma isso em uma string Unicode. errors opcionais são passados para o argumento errors do método encode() de str; o padrão é 'replace'. fallback_charset opcional especifica o conjunto de caracteres a ser usado se aquele no cabeçalho RFC 2231 não for conhecido pelo Python; o padrão é 'us-ascii'.

Por conveniência, se value passado para collapse_rfc2231_value() não for uma tupla, deve ser uma string e é retornado sem aspas.

email.utils.decode_params(params)

Decodifica a lista de parâmetros de acordo com RFC 2231. params é uma sequência de 2 tuplas contendo elementos do formulário (content-type, string-value).

Notas de Rodapé

1

Observa que o sinal do deslocamento de fuso horário é o oposto do sinal da variável time.timezone para o mesmo fuso horário; a última variável segue o padrão POSIX enquanto este módulo segue RFC 2822.