# `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__`()

    Returns input_charset as a string coerced to lower case. `__repr__()` is an alias for `__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`.