12.4. marshal — Sérialisation interne des objets Python

Ce module contient des fonctions permettant de lire et écrire des valeurs Python au format binaire. Ce format est propre à Python, mais indépendant de l’architecture de la machine (p. ex., vous pouvez écrire une valeur Python dans un fichier sur un PC, envoyer le fichier vers une machine Sun et la lire à nouveau). Les détails du format sont volontairement non documentés ; il peut changer d’une version Python à l’autre (bien que ce soit rarement le cas). 1

Ce module ne permet pas de « sérialiser » des objets de manière permanente. Pour des questions de sérialisation en général ou de transfert d’objets Python par des appels RPC, référez-vous aux modules pickle et shelve. Le module marshal existe principalement pour permettre la lecture et l’écriture de code « pseudo-compilé » pour les modules Python des fichiers .pyc. Par conséquent, les mainteneurs Python se réservent le droit de modifier le format marshal en cassant la rétrocompatibilité si besoin. Si vous sérialisez et dé-sérialisez des objets Python, utilisez plutôt le module pickle — les performances sont comparables, l’indépendance par rapport à la version est garantie, et pickle prend en charge une gamme d’objets beaucoup plus large que marshal.

Avertissement

N’utilisez pas le module marshal pour lire des données erronées ou malveillantes. Ne démantelez jamais des données reçues d’une source non fiable ou non authentifiée.

Tous les types d’objets Python ne sont pas pris en charge ; en général, seuls les objets dont la valeur est indépendante d’une invocation particulière de Python peuvent être écrits et lus par ce module. Les types suivants sont pris en charge : booléens, entiers, nombres à virgule flottante, nombres complexes, chaînes de caractères, octets, bytearrays, n-uplets, listes, ensembles, ensembles figés, dictionnaires et objets, étant entendu que les n-uplets, listes, ensembles, ensembles figés et dictionnaires sont pris en charge si les valeurs qu’ils contiennent sont elles-mêmes prises en charge. Les singletons None, Ellipsis et StopIteration peuvent également être « pseudo-compilés » et « dé-pseudo-compilés ». Pour le format des versions inférieures à 3, les listes récursives, les ensembles et les dictionnaires ne peuvent pas être écrits (voir ci-dessous).

Il existe des fonctions de lecture-écriture de fichiers ainsi que des fonctions opérant sur des objets octet.

Le module définit ces fonctions :

marshal.dump(value, file[, version])

Écrit la valeur sur le fichier ouvert. La valeur doit être un type pris en charge. Le fichier doit être un fichier binaire ouvert en écriture.

Si la valeur est (ou contient un objet qui est) d’un type non implémenté, une exception ValueError est levée — mais le contenu de la mémoire sera également écrit dans le fichier. L’objet ne sera pas correctement lu par load().

L’argument version indique le format de données que le dump doit utiliser (voir ci-dessous).

marshal.load(file)

Lit une valeur du fichier ouvert et la renvoie. Si aucune valeur valide n’est lue (p. ex. parce que les données ont un format décompilé incompatible avec une autre version de Python), EOFError, ValueError ou TypeError est levée. Le fichier doit être un fichier binaire ouvert en lecture.

Note

Si un objet contenant un type non pris en charge a été dé-compilé avec dump(), load() remplacera le type non « dé-compilable » par None.

marshal.dumps(value[, version])

Renvoie les octets qui seraient écrits dans un fichier par dump(value, file). La valeur doit être un type pris en charge. Lève une exception ValueError si la valeur a (ou contient un objet qui a) un type qui n’est pas pris en charge.

L’argument version indique le format de données que dumps doivent utiliser (voir ci-dessous).

marshal.loads(bytes)

Convertit le bytes-like object en une valeur. Si aucune valeur valide n’est trouvée, EOFError, ValueError ou TypeError est levée. Les octets supplémentaires de l’entrée sont ignorés.

De plus, les constantes suivantes sont définies :

marshal.version

Indique le format que le module utilise. La version 0 est le format originel, la version 1 partage des chaînes de caractères internes et la version 2 utilise un format binaire pour les nombres à virgule flottante. La version 3 ajoute la prise en charge de l’instanciation et de la récursivité des objets. La version actuelle est la 4.

Notes

1

Le nom de ce module provient d’un peu de terminologie utilisée par les concepteurs de Modula-3 (entre autres), qui utilisent le terme marshalling pour l’envoi de données sous une forme autonome. À proprement parler, to marshal signifie convertir certaines données d’une forme interne à une forme externe (dans une mémoire tampon RPC par exemple) et unmarshalling désigne le processus inverse.