12.2.4 Creare oggetti email e MIME da zero

Normalmente, si può ottenere una struttura di oggetti messaggio passando un file o del testo al parser, che analizza il testo e restituisce l'oggetto message principale. Comunque si può anche costruire una struttura di messaggi completamente da zero, o anche oggetti Message individuali a mano. In pratica, si può anche prendere una struttura esistente e aggiungere nuovi oggetti Message, spostarli, etc. etc.. Questo rende molto conveniente l'interfaccia per effettuare lo slicing-and-dicing dei messaggi MIME.

É possibile creare una nuova struttura di oggetti creando un'istanza Message, aggiungendo gli allegati e tutte le intestazioni appropriate a mano. Per i messaggi MIME però il package email fornisce alcune sotto classi convenienti per rendere il tutto più facile. Ogni sotto classe deve essere importata da un modulo con lo stesso nome della classe, dal package email. Per esempio:

import email.MIMEImage.MIMEImage

from email.MIMEText import MIMEText

Ecco la classe:

class MIMEBase( _maintype, _subtype, **_params)

Questa è la classe base per tutte le sotto classi di Message specifiche per MIME. Ordinariamente non si creeranno istanze specifiche di MIMEBase, anche se lo si potrebbe comunque fare. MIMEBase viene fornita principalmente come classe base utile per alcune specifiche sotto classi MIME-consapevoli.

_maintype è il tipo principale di Content-Type: (per esempio, text o image) e _subtype è il tipo secondario in Content-Type: (per esempio plain o gif). _params è un dizionario chiave/valore passato direttamente a Message.add_header().

La classe MIMEBase aggiunge sempre un'intestazione Content-Type: (basata su _maintype, _subtype e _params) ed un'intestazione MIME-Version: (sempre impostata a 1.0).

class MIMENonMultipart( ): Una sotto classe di MIMEBase, questa è una classe base intermedia per messaggi MIME che non sono multipart. Lo scopo principale di questa classe è di prevenire l'uso del metodo attach(), che ha senso solo per messaggi multipart. Se attach() viene chiamata, viene sollevata un'eccezione di tipo MultipartConversionError.
Nuovo nella versione 2.2.2.

class MIMEMultipart( [subtype[, boundary[, _subparts[, _params]]]])

Una sotto classe di MIMEBase, questa è una classe base intermedia per messaggi MIME che non sono multipart. L'argomento facoltativo _subtype ha valore predefinito a mixed, ma può essere utilizzato per specificare il sotto tipo del messaggio. Un'intestazione Content-Type: del tipo multipart/_subtype viene aggiunta all'oggetto del messaggio. Viene anche aggiunta un'intestazione MIME-Version:.

L'argomento facoltativo boundary è la stringa boundary multipart. Quando è None (il valore predefinito), il boundary (NdT: limite) viene calcolato quando necessario.

_subparts è una sequenza della sotto parte iniziale del carico utile. Deve essere possibile convertire questa sequenza in una lista. Si possono sempre allegare nuove sotto parti al messaggio utilizzando il metodo Message.attach().

Parametri addizionali per l'intestazione Content-Type: vengono presi dall'argomento parola chiave o passati nell'argomento _params, che è un dizionario di parole chiave.

Nuovo nella versione 2.2.2.

class MIMEAudio( _audiodata[, _subtype[, _encoder[, **_params]]])

Una sotto classe di MIMENonMultipart, la classe MIMEAudio viene utilizzata per creare oggetti messaggi MIME di tipo principale audio. _audiodata è una stringa contenente i dati audio grezzi. Se questi dati possono essere decodificati dal modulo standard di Python sndhdr, il sotto tipo viene automaticamente incluso nell'intestazione Content-Type:. Altrimenti si può esplicitamente specificare il sotto tipo audio attraverso il parametro _subtype. Se il tipo secondario non può essere determinato e _subtype non viene fornito, verrà sollevata un'eccezione di tipo TypeError.

Il parametro facoltativo _encoder è un oggetto eseguibile (per esempio una funzione) che effettuerà la vera codifica dei dati audio per il trasporto. Questo eseguibile prende un solo argomento, che è l'istanza di MIMEAudio. Si può utilizzare il metodo get_payload() e set_payload() per cambiare il carico utile alla forma codificata. Deve anche aggiungere le intestazioni Content-Transfer-Encoding: o altro che sia necessario, nell'oggetto messaggio. La codifica predefinita è base64. Vedere il modulo email.Encoders per una lista degli encoder built-in.

_params vengono passati direttamente attraverso il costruttore della classe base.

class MIMEImage( _imagedata[, _subtype[, _encoder[, **_params]]])

Una sotto classe di MIMENonMultipart, la classe MIMEImage viene utilizzata per creare oggetti MIME, principalmente del tipo image. _imagedata è la stringa che contiene i dati grezzi dell'immagine. Se questi dati possono essere decodificati dal modulo standard di Python imghdr, il sotto tipo viene automaticamente incluso nell'intestazione Content-Type:. Altrimenti potete esplicitamente specificare il sotto tipo dell'immagine tramite il parametro _subtype. Se il tipo secondario non può essere ricavato e _subtype non viene fornito, viene sollevata l'eccezione TypeError.

Il parametro facoltativo _encoder è un eseguibile (per esempio una funzione) che effettuerà la reale codifica dei dati dell'immagine per il trasporto. Questo eseguibile prende un argomento, che è l'istanza di MIMEImage. Deve utilizzare get_payload() e set_payload() per cambiare il carico utile nella forma codificata. Deve anche aggiungere ogni intestazione Content-Transfer-Encoding: o altro necessario all'oggetto messaggio. La codifica predefinita è base64. Vedere il modulo email.Encoders per una lista di tutti gli encoder built-in.

_params vengono passati direttamente al costruttore MIMEBase.

class MIMEMessage( _msg[, _subtype]): Una sotto classe di MIMENonMultipart, la classe MIMEMessage viene utilizzata per creare oggetti MIME, principalmente di tipo message. _msg viene utilizzato come carico utile e deve essere un'istanza della classe Message (o una sotto classe), altrimenti viene sollevata l'eccezione TypeError.
L'argomento facoltativo _subtype imposta il sotto tipo del messaggio; il valore predefinito è rfc822.

class MIMEText( _text[, _subtype[, _charset[, _encoder]]])

Una sotto classe di MIMENonMultipart, la classe MIMEText viene utilizzata per creare oggetti MIME, principalmente di tipo text. _text è la stringa per il carico utile. _subtype è il tipo secondario ed il valore predefinito è plain. _charset è il charset del testo e viene passato come parametro al costruttore di MIMENonMultipart; il valore predefinito è us-ascii. Non viene effettuata alcuna analisi per determinare la codifica del testo.

Deprecato dalla versione 2.2.2 di Python. L'argomento _encoding è considerato deprecato. La codifica adesso viene implicitamente basata sull'argomento _charset.

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