3.14.3 Uso

Per serializzare una gerarchia di oggetti, per prima cosa si deve creare un oggetto pickler, successivamente se ne richiami il metodo dump(). Per deserializzare un flusso di dati, si deve creare prima un oggetto unpickler, e poi se ne richiami il metodo load(). Il modulo pickle fornisce la seguente costante:

HIGHEST_PROTOCOL: Il protocollo con versione più alta disponibile. Questo valore può venire passato come un valore protocol. Nuovo nella versione 2.3.

Il modulo pickle fornisce le seguenti funzioni per rendere questo processo più funzionale:

dump( object, file[, protocol[, bin]])

Scrive una rappresentazione serializzata di object nell'oggetto file aperto file. Questo è equivalente a Pickler(file, protocol, bin).dump(object).

Se il parametro protocol viene omesso, viene utilizzato il protocollo versione 0. Se protocol viene specificato come un numero negativo o HIGHEST_PROTOCOL, il protocollo con il valore più alto viene utilizzato.

Modificato nella versione 2.3: È stato aggiunto il parametro protocol. Il parametro bin è deprecato e viene fornito soltanto per compatibilità all'indietro con le versioni precedenti. Al suo posto usate il parametro protocol.

Se l'argomento facoltativo bin è vero, viene utilizzato il formato binario di pickle; altrimenti, viene utilizzato il (meno efficiente) formato testo di pickle (per compatibilità all'indietro, questo è predefinito).

Il file deve avere un metodo write() che accetti un argomento di una singola stringa. Può quindi essere un oggetto file aperto in scrittura, un oggetto StringIO, o qualsiasi altro oggetto personalizzato che rispetti questa interfaccia.

load( file)

Legge una stringa dal file oggetto file aperto, e lo interpreta come un flusso di dati serializzato, ricostruendo e restituendo l'originale gerarchia dell'oggetto. Questo è l'equivalente di Unpickler(file).load().

file deve possedere due metodi, un metodo read() che prende un argomento di tipo intero e un metodo readline() che non richiede argomenti. Entrambi i metodi devono restituire una stringa. Così file può essere un oggetto file aperto in lettura, un oggetto StringIO, o qualsiasi altro oggetto personalizzato che rispetti questa interfaccia.

Questa funzione determina automaticamente se il flusso dei dati viene scritto in modo binario o meno.

dumps( object[, protocol[, bin]])

Restituisce una rappresentazione serializzata dell'oggetto come stringa, invece che scriverlo in un file.

Se il parametro protocol viene omesso, si utilizza il protocollo versione 0. Se protocol viene specificato con un valore negativo o con HIGHEST_PROTOCOL, verrà utilizzata la versione con il protocollo maggiore.

Modificato nella versione 2.3: Il parametro protocol è stato aggiunto. Il parametro bin è deprecato e viene fornito solo per compatibilità con le versioni precedenti. Al suo posto, usate il parametro protocol.

Se l'argomento facoltativo bin è vero, pickle viene usato in formato binario; altrimenti (ma meno efficiente) pickle viene usato in formato testo (predefinito).

loads( string): Legge da una stringa, una gerarchia dell'oggetto serializzato. I caratteri nella stringa successivi alla rappresentazione dell'oggetto serializzato vengono ignorati.

Il modulo pickle definisce anche tre eccezioni:

exception PickleError: Una classe comune per le altre eccezioni definite di seguito. Questa eredita da Exception.

exception PicklingError: Questa eccezione viene sollevata quando un oggetto non serializzabile viene passato al metodo dump().

exception UnpicklingError: Questa eccezione viene sollevata quando si verifica un problema effettuando la deserializzazione di un oggetto. Notate che altre eccezioni possono venire sollevate durante le operazioni di deserializzazione, incluse (ma non necessariamente limitate ad esse) AttributeError, EOFError, ImportError e IndexError.

Il modulo pickle esporta anche due oggetti chiamabili ^3.3, Pickler e Unpickler:

class Pickler( file[, protocol[, bin]])

Questa classe prende un oggetto file (o un oggetto con le medesime caratteristiche) sul quale scriverà un flusso di dati serializzati.

Se si omette il parametro protocol, viene usato protocol 0. Se si specifica protocol come un valore negativo, verrà usato il protocollo con versione più alta.

Modificato nella versione 2.3: Il parametro bin è deprecato e viene fornito solo per compatibilità all'indietro con le versioni precedenti. Al suo posto, usate il parametro protocol.

Se il parametro facoltativo bin è vero, indica a pickler di usare il più efficiente formato di serializzazione binario, altrimenti viene usato il formato ASCII (predefinito).

L'oggetto file deve avere il metodo write() che accetti una singola stringa di argomenti. Può essere perciò un oggetto file aperto, un oggetto StringIO, o ogni altro oggetto personalizzato che rispetti questa interfaccia.

Gli oggetti Pickler definiscono uno (o due) metodi pubblici:

dump( object): Scrive una rappresentazione serializzata di object nell'oggetto file aperto dato al costruttore. Sia il formato binario che il formato ASCII verranno usati, dipendentemente dal valore dell'opzione di bin passata al costruttore.

clear_memo( )

Ripulisce il ``memo'' del pickler. Il memo è la struttura di dati che ricorda quali oggetti sono già stati visti dal pickler, così che oggetti condivisi o ricorsivi vengano serializzati per riferimento e non per valore. Questo metodo è utile quando i pickler vengono riutilizzati.

Note: Prima di Python 2.3, clear_memo() era disponibile solo per i serializzatori creati da cPickle. Nel modulo pickle, i serializzatori hanno un'istanza variabile chiamata memo che è un dizionario Python. Così, per ripulire il memo per un modulo serializzatore pickle, si potrebbe fare come di seguito:

mypickler.memo.clear()

In codice che non necessiti di supportare vecchie versioni di Python, usate semplicemente clear_memo().

È possibile effettuare chiamate multiple al metodo dump() per la stessa istanza Pickler. Queste devono quindi essere equivalenti allo stesso numero di chiamate del metodo load() della corrispondente istanza Unpickler. Se lo stesso oggetto viene serializzato da chiamate multiple a dump(), il load() deve rendere tutti i riferimenti allo stesso oggetto. ^3.4

Gli oggetti Unpickler vengono definiti come:

class Unpickler( file): Questo prende un oggetto file (o un oggetto con le medesime caratteristiche) da cui leggerà un flusso di dati serializzati. Questa classe determina automaticamente se il flusso di dati è stato scritto in modo binario o meno, quindi non necessita di un'opzione come nella costruzione di Pickler.
file deve avere due metodi, un metodo read() che prende come argomento un intero, e un metodo readline() che non richiede argomenti. Entrambi i metodi devono restituire una stringa. Così file può essere un oggetto file aperto in lettura, un oggetto StringIO, o qualsiasi altro oggetto personalizzato che rispetti questa interfaccia.

Gli oggetti Unpickler hanno uno (o due ) metodi pubblici:

load( ): Legge una rappresentazione di un oggetto serializzato da un oggetto file aperto passato al costruttore, e restituisce l'oggetto ricostituito gerarchicamente come specificato al suo interno.

noload( ): Questo è identico a load() ad eccezione del fatto che non crea alcun oggetto. Ciò è utile principalmente per trovare quelli che vengono chiamati ``id persistenti'', referenziati all'interno di un flusso di dati serializzato. Vedete la sottostante sezione 3.14.5 per ulteriori dettagli.
Note: il metodo noload() è l'unico attualmente disponibile per gli oggetti Unpickler creati dal modulo cPickle. I moduli pickle non serializzabili non hanno il metodo noload().

Footnotes

... chiamabili ^3.3: Nel modulo pickle questi oggetti sono delle classi, che possono diventare sotto classi personalizzate. Tuttavia, nel modulo cPickle questi oggetti chiamabili sono funzioni factory e non è possibile derivarne delle sotto classi. Una comune ragione per derivare sotto classi consiste nel voler controllare quale oggetto può attualmente venire deserializzato. Vedete la sezione 3.14.6 per maggiori dettagli.
... oggetto.^3.4: Attenzione: questo viene inteso per la serializzazione di oggetti multipli senza modificare gli oggetti stessi, o loro parti. Se modificate un oggetto e quindi lo serializzate ancora usando la stessa instanza Pickler, l'oggetto non verrà serializzato ancora -- un riferimento ad esso viene serializzato e Unpickler restituirà il vecchio valore, non quello modificato. Ci sono due problemi qui: (1) individuare i cambiamenti, e (2) combinare un insieme minimo di cambiamenti. La Garbage Collection qui può anche diventare un problema.

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