3.19 marshal -- Serializzazione di oggetti interna a Python

Questo modulo contiene funzioni che possono leggere e scrivere valori Python in formato binario. Il formato è specifico di Python ma indipendente dall'architettura della macchina (p.es., potreste scrivere un valore Python in un file su di un pc, trasportare il file su una Sun e leggerlo lì sopra). I dettagli sul formato non vengono documentati di proposito; potrebbe cambiare attraverso le varie versioni di Python (anche se avviene raramente).3.12

Questo non è un modulo generale di ``persistenza''. Per la persistenza generale ed il trasferimento di oggetti Python attraverso chiamate RPC, vedete i moduli pickle e shelve. Il modulo marshal esiste principalmente per leggere e scrivere codice ``pseudo compilato'' per moduli Python in file .pyc. Quindi, i manutentori di Python si riservano il diritto di modificare il formato marshal per renderlo incompatibile con le versioni precedenti, se dovesse presentarsene la necessità. Se si stanno serializzando e deserializzando oggetti Python, è consigliato invece utilizzare il modulo pickle.

il modulo marshal non viene considerato sicuro contro dati errati o costruiti maliziosamente. Non effettuate mai deserializzazioni di tipo unmarshal di dati ricevuti da una fonte non autenticata o non fidata.

Non tutti i tipi di oggetti Python vengono supportati; in generale, solo gli oggetti il cui valore è indipendente da una particolare invocazione di Python possono venire scritti e letti da questo modulo. I seguenti tipi sono supportati: None, interi, interi long, numeri in virgola mobile, stringhe, oggetti Unicode, tuple, liste, dizionari e codice oggetto, dove dovrebbe essere sottinteso che tuple, liste o dizionari, vengono supportati se i valori in essi contenuti sono a loro volta supportati; liste e dizionari ricorsivi non dovrebbero venire scritti (causeranno cicli infiniti).

Avvertimento: Su macchine dove il tipo degli interi long in C ha più di 32 bit (tipo i DEC alpha), è possibile creare interi Python ordinari più lunghi di 32 bit. Si può allora verificare che se qualche intero viene serializzato con marshal e reinterpretato su di una macchina dove gli interi long in C hanno solo 32 bit, venga resituito un intero long Python. Nonostante la differenza di tipo, il valore numerico è lo stesso. (Questo comportamento è nuovo in Python 2.2. Nelle precedenti versioni, tutti tranne i meno significativi dei 32 bit del valore venivano persi, e veniva stampato un messaggio di avviso).

Esistono funzioni di lettura/scrittura sui file simili alle funzioni che operano sulle stringhe.

Il modulo definisce queste funzioni:

dump( value, file)
Scrive il valore nel file aperto. Il valore deve essere un tipo supportato. Il file deve essere un file oggetto di tipo aperto come sys.stdout, come valore restituito da open() o posix.popen(). Deve venire aperto in modo binario ('wb' o 'w+b').

Se il valore ha (o contiene un oggetto che ha) un tipo non supportato, viene sollevata un'eccezione ValueError -- ma valori inutili verranno comunque scritti nel file. L'oggetto non verrà corettamente reinterpretato da load().

load( file)
Legge e restituisce un valore dal file aperto. Se non viene letto un valore valido, viene sollevata un'eccezione EOFError, ValueError o TypeError. Il file deve essere un file oggetto di tipo aperto in modo binario ('rb' o 'r+b').

Se un oggetto contenente un tipo non supportato è stato serializzato (da marshal) con dump(), load(), sostituirà None ai tipi che non possono venire deserializzati.

dumps( valore)
Restituisce la stringa che verrebbe scritta in un file da dump(valore, file). Il valore deve essere un tipo supportato. Solleva un'eccezione ValueError se il valore ha (o contiene un oggetto che ha) un tipo non supportato.

loads( string)
Converte la stringa in un valore. Se non viene trovato un valore valido, viene sollevata un'eccezione tra EOFError, ValueError e TypeError. I caratteri superflui nella stringa vengono ignorati.


Footnotes

... raramente).3.12
Il nome di questo modulo deriva in parte dalla terminologia usata dai progettisti di Modula-3 (tra gli altri), che usano il termine ``marshalling'' per la trasmissinione di dati in un formato indipendente. Brevemente, ``to marshal'' significa convertire dei dati da un formato interno ad uno esterno (in un buffer RPC per esempio) e ``unmarshalling'' indica il procedimento inverso.
Vedete Circa questo documento... per informazioni su modifiche e suggerimenti.