# 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.