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 consciente. Se chamado sem argumentos, retorna a hora atual. Caso contrário, o argumento dt deve ser uma instância
datetime
e é convertido para o fuso horário local de acordo com o banco de dados de fuso horário do sistema. Se dt for ingênuo (ou seja,dt.tzinfo
forNone
), será presumido como estando no horário local. O parâmetro isdst é ignorado.Adicionado na versão 3.3.
Deprecated since version 3.12, will be removed in version 3.14: O parâmetro isdst.
- email.utils.make_msgid(idstring=None, domain=None)¶
Retorna uma string adequada para um cabeçalho Message-ID compatível com RFC 2822. O idstring opcional, se fornecido, é uma string usada para fortalecer a exclusividade do ID da mensagem. O domain Opcional, 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: Adicionada 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 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, *, strict=True)¶
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.Se strict for verdadeiro, usa um analisador sintático estrito que rejeite entradas malformadas.
Alterado na versão 3.12.6: Adiciona o parâmetro opcional strict e rejeita entradas malformadas por padrão.
- email.utils.formataddr(pair, charset='utf-8')¶
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.O charset opcional é o conjunto de caracteres que será usado na codificação RFC 2047 do
realname
se orealname
contiver caracteres não-ASCII. Pode ser uma instância destr
ou aCharset
. O padrão éutf-8
.Alterado na versão 3.3: Adicionada a opção charset.
- email.utils.getaddresses(fieldvalues, *, strict=True)¶
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 porMessage.get_all
.Se strict for verdadeiro, usa um analisador sintático estrito que rejeite entradas malformadas.
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)
Alterado na versão 3.12.6: Adiciona o parâmetro opcional strict e rejeita entradas malformadas por padrão.
- 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 paratime.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)¶
Executa a mesma função que
parsedate()
, mas retornaNone
ou uma tupla de 10; os primeiros 9 elementos formam uma tupla que pode ser passada diretamente paratime.mktime()
, e o décimo é o deslocamento do fuso horário da data do UTC (que é o termo oficial para o horário de Greenwich) [1]. Se a string de entrada não tem fuso horário, o último elemento da tupla retornado é0
, que representa UTC. Observe que os índices 6, 7 e 8 da tupla de resultado não podem ser usados.
- email.utils.parsedate_to_datetime(date)¶
O inverso de
format_datetime()
. Desempenha a mesma função queparsedate()
, mas em caso de sucesso retorna umdatetime
; caso contrário,ValueError
é levantada se date contiver um valor inválido, como uma hora maior que 23 ou uma diferença de fuso horário não entre -24 e 24 horas. Se a data de entrada tem um fuso horário de-0000
, odatetime
será umdatetime
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, odatetime
será umdatetime
consciente com o correspondente atimezone
tzinfo
.Adicionado 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 forNone
, 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()
etime.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 asciiGMT
, ao invés de um numérico-0000
. Isso é necessário para alguns protocolos (como HTTP). Isso se aplica apenas quando localtime forFalse
. O padrão éFalse
.
- email.utils.format_datetime(dt, usegmt=False)¶
Como
formatdate
, mas a entrada é uma instância dedatetime
. 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 umdatetime
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 comoTrue
, caso em que a stringGMT
é 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.Adicionado na versão 3.3.
- 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étodoencode()
destr
; 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é