# `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).

  Raises an auditing event `marshal.dumps` with arguments `value`, `version`.

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.

  Raises an auditing event `marshal.load` with no arguments.

  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`.

  Modifié dans la version 3.10: This call used to raise a `code.__new__` audit event for each code object. Now it raises a single `marshal.load` event for the entire load operation.

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).

  Raises an auditing event `marshal.dumps` with arguments `value`, `version`.

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.

  Raises an auditing event `marshal.loads` with argument `bytes`.

  Modifié dans la version 3.10: This call used to raise a `code.__new__` audit event for each code object. Now it raises a single `marshal.loads` event for the entire load operation.

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.