# `email.charset`: Representing character sets

Código-fonte: Lib/email/charset.py

Este módulo faz parte da API de e-mail legada (`Compat32`). Na nova API, apenas a tabela de apelidos é usada.

O texto restante nesta seção é a documentação original do módulo.

Este módulo fornece uma classe `Charset` para representar conjuntos de caracteres e conversões de conjuntos de caracteres em mensagens de e-mail, bem como um registro de conjuntos de caracteres e vários métodos práticos para manipular esse registro. Instâncias de `Charset` são usadas em vários outros módulos do pacote `email`.

Importa esta classe do módulo `email.charset`.

class email.charset.Charset(input_charset=DEFAULT_CHARSET)

  Mapeia conjuntos de caracteres para suas propriedades de e-mail.

  Esta classe fornece informações sobre os requisitos impostos ao e-mail para um conjunto de caracteres específico. Também fornece rotinas práticas para conversão entre conjuntos de caracteres, considerando a disponibilidade dos codecs aplicáveis. Dado um conjunto de caracteres, ela fará o possível para fornecer informações sobre como usá-lo em uma mensagem de e-mail de forma compatível com RFC.

  Certos conjuntos de caracteres devem ser codificados com quoted-printable ou base64 quando usados em cabeçalhos ou corpos de e-mail. Certos conjuntos de caracteres devem ser convertidos diretamente e não são permitidos em e-mails.

  O input_charset opcional é descrito abaixo; ele é sempre convertido para letras minúsculas. Após ser normalizado por apelido, ele também é usado como uma consulta no registro de conjuntos de caracteres para descobrir a codificação do cabeçalho, a codificação do corpo e o codec de conversão de saída a serem usados para o conjunto de caracteres. Por exemplo, se input_charset for `iso-8859-1`, os cabeçalhos e corpos serão codificados usando quoted-printable e nenhum codec de conversão de saída será necessário. Se input_charset for `euc-jp`, os cabeçalhos serão codificados em base64, os corpos não serão codificados, mas o texto de saída será convertido do conjunto de caracteres `euc-jp` para o conjunto de caracteres `iso-2022-jp`.

  Instâncias `Charset` têm os seguintes atributos de dados:

  input_charset

    O conjunto de caracteres inicial especificado. Apelidos comuns são convertidos em seus nomes de e-mail oficiais (por exemplo, `latin_1` é convertido para `iso-8859-1`). O padrão é `us-ascii` de 7 bits.

  header_encoding

    If the character set must be encoded before it can be used in an email header, this attribute will be set to `Charset.QP` (for quoted-printable), `Charset.BASE64` (for base64 encoding), or `Charset.SHORTEST` for the shortest of QP or BASE64 encoding. Otherwise, it will be `None`.

  body_encoding

    Same as header_encoding, but describes the encoding for the mail message’s body, which indeed may be different than the header encoding. `Charset.SHORTEST` is not allowed for body_encoding.

  output_charset

    Alguns conjuntos de caracteres precisam ser convertidos antes de serem usados em cabeçalhos ou corpos de e-mail. Se input_charset for um deles, este atributo conterá o nome do conjunto de caracteres para o qual a saída será convertida. Caso contrário, será `None`.

  input_codec

    O nome do codec Python usado para converter o input_charset para Unicode. Se nenhum codec de conversão for necessário, este atributo será `None`.

  output_codec

    O nome do codec Python usado para converter Unicode para o output_charset. Se nenhum codec de conversão for necessário, este atributo terá o mesmo valor que o input_codec.

  Instâncias `Charset` também têm os seguintes métodos:

  get_body_encoding()

    Retorna a codificação de transferência de conteúdo usada para codificação do corpo.

    Esta é a string `quoted-printable` ou `base64`, dependendo da codificação usada, ou é uma função, caso em que você deve chamar a função com um único argumento, sendo o objeto Message codificado. A função deve então definir o próprio cabeçalho Content-Transfer-Encoding com o valor apropriado.

    Retorna a string `quoted-printable` se body_encoding for `QP`, retorna a string `base64` se body_encoding for `BASE64` e retorna a string `7bit` caso contrário.

  get_output_charset()

    Retorna o conjunto de caracteres de saída.

    Este é o atributo output_charset se não for `None`, caso contrário, é input_charset.

  header_encode(string)

    Codifica o cabeçalho com a string string.

    O tipo de codificação (base64 ou quoted-printable) será baseado no atributo header_encoding.

  header_encode_lines(string, maxlengths)

    Codifica um cabeçalho de uma string convertendo-a primeiro em bytes.

    Isso é semelhante a `header_encode()`, exceto que a string é ajustada aos comprimentos máximos de linha, conforme fornecido pelo argumento maxlengths, que deve ser um iterador: cada elemento retornado deste iterador fornecerá o próximo comprimento máximo de linha.

  body_encode(string)

    Codifica o corpo com a string string.

    O tipo de codificação (base64 ou quoted-printable) será baseado no atributo body_encoding.

  A classe `Charset` também fornece vários métodos para dar suporte a operações padrão e funções embutidas.

  __str__()

    Retorna input_charset como uma string convertida para minúsculas. `__repr__()` é um apelido para `__str__()`.

  __eq__(other)

    Este método permite que você compare duas instâncias `Charset` para verificar a igualdade.

  __ne__(other)

    Este método permite que você compare duas instâncias `Charset` para verificar a desigualdade.

O módulo `email.charset` também fornece as seguintes funções para adicionar novas entradas ao conjunto global de caracteres, apelidos e registros de codec:

email.charset.add_charset(charset, header_enc=None, body_enc=None, output_charset=None)

  Adiciona propriedades de caracteres ao registro global.

  charset é o conjunto de caracteres de entrada e deve ser o nome canônico de um conjunto de caracteres.

  Optional header_enc and body_enc is either `Charset.QP` for quoted-printable, `Charset.BASE64` for base64 encoding, `Charset.SHORTEST` for the shortest of quoted-printable or base64 encoding, or `None` for no encoding. `SHORTEST` is only valid for header_enc. The default is `None` for no encoding.

  output_charset opcional é o conjunto de caracteres que a saída deve conter. As conversões prosseguirão do conjunto de caracteres de entrada para Unicode e para o conjunto de caracteres de saída quando o método `Charset.convert()` for chamado. O padrão é gerar a saída no mesmo conjunto de caracteres da entrada.

  Tanto input_charset quanto output_charset devem ter entradas de codec Unicode no mapeamento de conjunto de caracteres para codec do módulo; use `add_codec()` para adicionar codecs que o módulo não conhece. Consulte a documentação do módulo `codecs` para obter mais informações.

  O registro do conjunto de caracteres global é mantido no dicionário global do módulo `CHARSETS`.

email.charset.add_alias(alias, canonical)

  Adicione um apelido para o conjunto de caracteres. alias é o nome do alias, por exemplo, `latin-1`. canonical é o nome canônico do conjunto de caracteres, por exemplo, `iso-8859-1`.

  O registro global de apelido de conjunto de caracteres é mantido no dicionário global do módulo `ALIASES`.

email.charset.add_codec(charset, codecname)

  Adiciona um codec que mapeia caracteres no conjunto de caracteres fornecido para e a partir do Unicode.

  charset é o nome canônico de um conjunto de caracteres. codecname é o nome de um codec Python, conforme apropriado para o segundo argumento do método `encode()` do `str`.