12.2.3 Generare documenti MIME

Una delle operazioni più comuni è generare la versione testuale del messaggio di email rappresentato da una struttura di oggetti messaggio. È necessario farlo per inviare il messaggio attraverso i moduli smtplib o nntplib, o stampare il messaggio sulla console. Prendere la struttura degli oggetti messaggio e generare un documento testuale è il lavoro della classe Generator.

Ancora, come con il modulo email.Parser, non si è limitati alle funzionalità del generatore incluso; è possibile scriverne uno da zero. Comunque il generatore incluso sa come generare la maggior parte delle email in un modo compatibile con lo standard, dovrebbe gestire messaggi MIME e non MIME in modo adeguato ed è progettato in modo che la trasformazione da testo a struttura del messaggio attraverso la classe Parser e di nuovo in testo sia ugualmente adeguata (l'input è identico all'output).

Questi sono i metodi pubblici della classe Generator:

class Generator( outfp[, mangle_from_[, maxheaderlen]])

Il costruttore della classe Generator riceve in input un oggetto di tipo file chiamato outfp come argomento. outfp deve supportare il metodo write() ed essere utilizzabile come file di output in un'istruzione print di Python.

Il parametro facoltativo mangle_from_ è un'opzione che, quando True, inserisce il carattere ">" di fronte a tutte le linee nel corpo dell'email che iniziano esattamente con "From ", per esempio From seguito da uno spazio all'inizio della riga. Questo è il solo modo garantito come portabile per evitare che queste righe siano scambiate per un separatore dell'intestazione della busta in formato mailbox Unix (vedere WHY THE CONTENT-LENGTH FORMAT IS BAD per i dettagli). Il valore predefinito di mangle_from_ è True, ma si potrebbe volerlo impostare a False se non si sta scrivendo un file in formato Unix mailbox.

L'argomento facoltativo maxheaderlen specifica la lunghezza massima per un'intestazione non continuativa. Quando una riga di intestazione è più lunga di maxheaderlen (in caratteri, con i caratteri di tabulazione espansi ad 8 spazi) l'intestazione viene separata come definito nella classe email.Header. Impostare a zero per disabilitare la separazione delle intestazioni. Il valore predefinito è 78, come raccomandato (ma non richiesto) dall'RFC 2822.

Gli altri metodi pubblici di Generator sono:

flatten( msg[, unixfrom])

Stampa la rappresentazione testuale della struttura degli oggetti messaggio originati da msg al file in output specificato quando l'istanza Generator è stata creata. Le sotto parti sono visitate in profondità e il testo risultante verrà propriamente codificato in MIME.

L'argomento facoltativo unixfrom è un'opzione che forza la stampa del delimitatore dell'intestazione della busta prima dell'intestazione RFC 2822 dell'oggetto messaggio principale. Se l'oggetto principale non ha un'intestazione di busta, ne viene messa una standard. Il valore predefinito è False, per inibire la stampa del delimitatore di busta.

Notare che per le sotto parti, non viene stampata alcuna intestazione di busta.

Nuovo nella versione 2.2.2.

clone( fp): Restituisce un clone indipendente dell'istanza di Generator, con le stesse identiche opzioni.
Nuovo nella versione 2.2.2.

write( s): Scrive la stringa s nell'oggetto file sottostante, per esempio outfp passato al costruttore di Generator. Questo fornisce un'interfaccia sufficientemente simile a file a Generator, da poter essere usata in un istruzione print estesa.

Per convenienza, vedere i metodi Message.as_string() e str(aMessage), a.k.a. Message.__str__(), che semplificano la generazione di una stringa formattata che rappresenta un oggetto messaggio. Per maggiori dettagli, vedere email.Message.

Il modulo email.Generator fornisce anche una classe derivata, chiamata DecodedGenerator, che è simile alla classe base Generator, ad accezione del fatto che le sotto parti non text vengono sostituite con una stringa di formattazione rappresentante la parte.

class DecodedGenerator( outfp[, mangle_from_[, maxheaderlen[, fmt]]])

Questa classe, derivata da Generator, attraversa tutte le sotto parti del messaggio. Se la sotto parte è principalmente text, stampa il carico utile decodificato della sotto parte. I parametri facoltativi _mangle_from_ e maxheaderlen sono esattamente come nella classe base Generator.

Se la sotto parte non è principalmente text, l'argomento facoltativo fmt è una stringa di formattazione che viene usata in sostituzione del carico utile del messaggio. fmt viene espanso con le seguenti parole chiave, "%(keyword)s":

type - Il tipo MIME completo della parte non text
maintype - Tipo MIME principale della parte non text
subtype - Tipo Sub-MIME della parte non text
filename - Nome del file della parte non text
description - Descrizione associata alla parte non text
encoding - Codifica del trasferimento dei contenuti della parte non text

Il valore predefinito di fmt è None, a significare

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

Nuovo nella versione 2.2.2.

Vedete Circa questo documento... per informazioni su modifiche e suggerimenti.