email.generator: Geração de documentos MIME

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

Uma das tarefas mais comuns é gerar a versão plana (serializada) da mensagem de e-mail representada por uma estrutura de objeto de mensagem. Você precisará fazer isso se quiser enviar sua mensagem via smtplib.SMTP.sendmail() ou exibir a mensagem no console. A tarefa das classes geradoras é pegar uma estrutura de objeto de mensagem e produzir uma representação serializada.

Assim como no módulo email.parser, você não está limitado à funcionalidade do gerador integrado; você mesmo pode criar um do zero. No entanto, o gerador integrado sabe como gerar a maioria dos e-mails em conformidade com os padrões, deve lidar perfeitamente com mensagens de e-mail MIME e não MIME e foi projetado para que as operações de análise e geração orientadas a bytes sejam inversas, presumindo que a mesma policy não transformadora seja usada para ambas. Ou seja, analisar o fluxo de bytes serializado por meio da classe BytesParser e, em seguida, regenerar o fluxo de bytes serializado usando BytesGenerator deve produzir uma saída idêntica à entrada [1]. (Por outro lado, usar o gerador em um EmailMessage construído pelo programa pode resultar em alterações no objeto EmailMessage à medida que os padrões são preenchidos.)

A classe Generator pode ser usada para simplificar uma mensagem em uma representação serializada de texto (em oposição a binária), mas como o Unicode não pode representar dados binários diretamente, a mensagem é necessariamente transformada em algo que contém apenas caracteres ASCII, usando as técnicas de codificação de transferência de conteúdo RFC de e-mail padrão para codificar mensagens de e-mail para transporte em canais que não são “limpos de 8 bits”.

Para acomodar o processamento reproduzível de mensagens assinadas por SMIME, Generator desabilita a dobragem de cabeçalho para partes de mensagens do tipo multipart/signed e todas as subpartes.

class email.generator.BytesGenerator(outfp, mangle_from_=None, maxheaderlen=None, *, policy=None)

Retorna um objeto BytesGenerator que gravará qualquer mensagem fornecida ao método flatten(), ou qualquer texto codificado surrogateescape fornecido ao método write(), no objeto arquivo ou similar outfp. outfp deve oferecer suporte a um método write que aceite dados binários.

Se o mangle_from_ opcional for True, coloca um caractere > na frente de qualquer linha no corpo que comece com a string exata "From ", ou seja, From seguido por um espaço no início de uma linha. mangle_from_ assume por padrão o valor da configuração mangle_from_ da policy (que é True para a política compat32 e False para todas as outras). mangle_from_ deve ser usado quando as mensagens são armazenadas no formato mbox do Unix (consulte mailbox e WHY THE CONTENT-LENGTH FORMAT IS BAD).

Se maxheaderlen não for None, redobra quaisquer linhas de cabeçalho maiores que maxheaderlen ou, se for 0, não redobra nenhum cabeçalho. Se manheaderlen for None (o padrão), redobra os cabeçalhos e outras linhas de mensagem de acordo com as configurações da policy.

Se policy for especificado, usa essa política para controlar a geração de mensagens. Se policy for None (o padrão), usa a política associada ao objeto Message ou EmailMessage passado para flatten para controlar a geração de mensagens. Consulte email.policy para obter detalhes sobre o que policy controla.

Adicionado na versão 3.2.

Alterado na versão 3.3: Adicionada o argumento nomeado policy.

Alterado na versão 3.6: O comportamento padrão dos parâmetros mangle_from_ e maxheaderlen é seguir a política.

flatten(msg, unixfrom=False, linesep=None)

Exibe a representação textual da estrutura do objeto de mensagem com raiz em msg no arquivo de saída especificado quando a instância BytesGenerator foi criada.

Se a opção policy cte_type for 8bit (o padrão), copia todos os cabeçalhos da mensagem original analisada que não tenham sido modificados para a saída, com todos os bytes com o bit mais alto definido reproduzidos como no original, e preserva a Content-Transfer-Encoding não ASCII de quaisquer partes do corpo que os contenham. Se cte_type for 7bit, converte os bytes com o bit mais alto definido, conforme necessário, usando uma Content-Transfer-Encoding compatível com ASCII. Ou seja, transforma partes com Content-Transfer-Encoding não ASCII (Content-Transfer-Encoding: 8bit) em um Content-Transfer-Encoding compatível com ASCII e codifica bytes não ASCII inválidos para RFC em cabeçalhos usando o conjunto de caracteres MIME unknown-8bit, tornando-os compatíveis com RFC.

Se unixfrom for True, exibe o delimitador de cabeçalho de envelope usado pelo formato de caixa de correio Unix (consulte mailbox) antes do primeiro dos cabeçalhos RFC 5322 do objeto de mensagem raiz. Se o objeto raiz não tiver cabeçalho de envelope, crie um padrão. O padrão é False. Observe que, para subpartes, nenhum cabeçalho de envelope é exibido.

Se linesep não for None, usa-o como caractere separador entre todas as linhas da mensagem simplificada. Se linesep for None (o padrão), usa o valor especificado na policy.

clone(fp)

Retorna um clone independente desta instância BytesGenerator com exatamente as mesmas configurações de opção e fp como o novo outfp.

write(s)

Codifica s usando o codec ASCII e o tratador de erros surrogateescape e passa-o para o método write do outfp passado ao construtor BytesGenerator.

Para facilitar, EmailMessage fornece os métodos as_bytes() e bytes(aMessage) (também conhecidos como __bytes__()), que simplificam a geração de uma representação binária serializada de um objeto de mensagem. Para mais detalhes, consulte email.message.

Como strings não podem representar dados binários, a classe Generator deve converter quaisquer dados binários em qualquer mensagem que ela nivele para um formato compatível com ASCII, convertendo-os para um Content-Transfer_Encoding compatível com ASCII. Usando a terminologia dos RFCs de e-mail, você pode pensar nisso como Generator serializando para um fluxo de E/S que não é “limpo em 8 bits”. Em outras palavras, a maioria das aplicações usará BytesGenerator, e não Generator.

class email.generator.Generator(outfp, mangle_from_=None, maxheaderlen=None, *, policy=None)

Retorna um objeto Generator que gravará qualquer mensagem fornecida ao método flatten(), ou qualquer texto fornecido ao método write(), no objeto arquivo ou similar outfp. outfp deve oferecer suporte a um método write que aceite dados string.

Se o mangle_from_ opcional for True, coloca um caractere > na frente de qualquer linha no corpo que comece com a string exata "From ", ou seja, From seguido por um espaço no início de uma linha. mangle_from_ assume por padrão o valor da configuração mangle_from_ da policy (que é True para a política compat32 e False para todas as outras). mangle_from_ deve ser usado quando as mensagens são armazenadas no formato mbox do Unix (consulte mailbox e WHY THE CONTENT-LENGTH FORMAT IS BAD).

Se maxheaderlen não for None, redobra quaisquer linhas de cabeçalho maiores que maxheaderlen ou, se for 0, não redobra nenhum cabeçalho. Se manheaderlen for None (o padrão), redobra os cabeçalhos e outras linhas de mensagem de acordo com as configurações da policy.

Se policy for especificado, usa essa política para controlar a geração de mensagens. Se policy for None (o padrão), usa a política associada ao objeto Message ou EmailMessage passado para flatten para controlar a geração de mensagens. Consulte email.policy para obter detalhes sobre o que policy controla.

Alterado na versão 3.3: Adicionada o argumento nomeado policy.

Alterado na versão 3.6: O comportamento padrão dos parâmetros mangle_from_ e maxheaderlen é seguir a política.

flatten(msg, unixfrom=False, linesep=None)

Exibe a representação textual da estrutura do objeto de mensagem com raiz em msg no arquivo de saída especificado quando a instância Generator foi criada.

Se a opção policy cte_type for 8bit, gera a mensagem como se a opção estivesse definida como 7bit. (Isso é necessário porque strings não podem representar bytes não ASCII.) Converte quaisquer bytes com o bit mais alto definido, conforme necessário, usando uma Content-Transfer-Encoding compatível com ASCII. Ou seja, transforma partes com Content-Transfer-Encoding não ASCII (Content-Transfer-Encoding: 8bit) em um Content-Transfer-Encoding compatível com ASCII e codifica bytes não ASCII inválidos para RFC em cabeçalhos usando o conjunto de caracteres MIME unknown-8bit, tornando-os compatíveis com RFC.

Se unixfrom for True, exibe o delimitador de cabeçalho de envelope usado pelo formato de caixa de correio Unix (consulte mailbox) antes do primeiro dos cabeçalhos RFC 5322 do objeto de mensagem raiz. Se o objeto raiz não tiver cabeçalho de envelope, crie um padrão. O padrão é False. Observe que, para subpartes, nenhum cabeçalho de envelope é exibido.

Se linesep não for None, usa-o como caractere separador entre todas as linhas da mensagem simplificada. Se linesep for None (o padrão), usa o valor especificado na policy.

Alterado na versão 3.2: Adicionado suporte para recodificação de corpos de mensagens 8bit e o argumento linesep.

clone(fp)

Retorna um clone independente desta instância Generator com exatamente as mesmas opções e fp como o novo outfp.

write(s)

Escreve s no método write do outfp passado ao construtor de Generator. Isso fornece API arquivo ou similar suficiente para que instâncias de Generator sejam usadas na função print().

Para facilitar, EmailMessage fornece os métodos as_string() e str(aMessage) (também conhecidos como __str__()), que simplificam a geração de uma representação de string formatada de um objeto de mensagem. Para mais detalhes, consulte email.message.

O módulo email.generator também fornece uma classe derivada, DecodedGenerator, que é como a classe base Generator, exceto que as partes não-text não são serializadas, mas são representadas no fluxo de saída por uma string derivada de um modelo preenchido com informações sobre a parte.

class email.generator.DecodedGenerator(outfp, mangle_from_=None, maxheaderlen=None, fmt=None, *, policy=None)

Age como Generator, exceto que para qualquer subparte da mensagem passada para Generator.flatten(), se a subparte for do tipo principal text, exibe a carga decodificada da subparte e, se o tipo principal não for text, em vez de exibi-la, preenche a string fmt usando informações da parte e exibe a string preenchida resultante.

Para preencher fmt, executa fmt % part_info, onde part_info é um dicionário composto pelas seguintes chaves e valores:

  • type – Tipo MIME completo da parte não-text

  • maintype – Tipo MIME principal da parte não-text

  • subtype – Tipo sub-MIME da parte não-text

  • filename – Nome de arquivo da parte não-text

  • description – Descrição associada à parte não-text

  • encoding – Codificação de transferência de conteúdo da parte não-text

Se fmt for None, usa o seguinte fmt padrão:

“[Non-text (%(type)s) part of message omitted, filename %(filename)s]”

Os opcionais _mangle_from_ e maxheaderlen são como os da classe base Generator.

Notas de rodapé