Tous les types d'objets Python ne sont pas supportés: 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
supportés: None, entiers, entiers longs, nombres à virgule flottante,
chaînes de caractères, objets Unicode, tuples, listes, dictionnaires, et
objets code ; étant bien entendu que les tuples, listes et dictionnaires
ne sont supportés que si les valeurs qu'ils contiennent sont eux-mêmes
supportés; et les listes et dictionnaires récursifs ne doivent pas
être écrits (ils provoqueront des boucles infinies).
Attention: Sur les machines pour lesquelles le type long intdu C a plus de 32 bits (comme l'Alpha de DEC) il est possible de créer des
entiers simples Python qui ont plus de 32 bits. Comme le module marshal
dans son état actuel utilise 32 bits pour transférer des entiers simples,
de telles values sont tronquées, sans rien signaler. Ceci a un effet
particulier sur l'utilisation d'entiers littéraux très longs dans les
modules Python - ils seront acceptés par l'analyseur sur de telles machines,
mais seront tronqués sans rien dire quand le module est lu depuis le
fichier .pyc.
2
Il existe des fonctions qui lisent et écrivent des fichiers aussi
bien que des fonctions qui opèrent sur des chaînes de caractères.
Le module définit les fonctions suivantes:
dump(valeur, fichier)
- Ecrit la valeur dans le fichier ouvert. La valeur doit être d'un
type supporté.Le fichier doit être un objet fichier ouvert, tel
que
sys.stdout ou le résultat d'un open() ou d'un
posix.popen(). Il doit être ouvert en mode binaire
('wb' ou 'w+b').
Si la valeur est d'un type non supporté (ou contient des valeurs d'un
type non supporté), une exception ValueError est déclenchée -
mais des données incohérentes seront tout de même écrites dans le fichier.
L'objet ne sera pas relu correctement par load().
load(fichier)
- Lit une valeur depuis le fichier ouvert et la retourne. Si aucune valeur
valide n'est lue, déclenche EOFError, ValueError
ou TypeError. Le fichier doit être un fichier ouvert en mode
binaire (
'rb' ou 'r+b').
Avertissement: Si un objet contenant un type non supporté a été
marshallé avec dump(), load() substitutera
None au type non marshallable.
dumps(valeur)
- Retourne la chaîne de caractères qui serait écrite dans un fichier par
dump(valeur, fichier). La valeur doit être d'un type
supporté. Déclenche une exception ValueError si la valeur
est d'un type non supporté, ou contient au moins un objet d'un type non
supporté.
loads(chaine)
- Convertit la chaîne en une valeur. Si aucune valeur valide n'est trouvée,
déclenche EOFError, ValueError ou
TypeError. Les caractères supplémentaires de la
chaîne sont ignorés.
Notes
- 1
- Le nom de ce module provient d'un point de terminologie
utilisé par les concepteurs de Modula-3 (entre autres), qui utilisent
le terme ``marshalling'' pour le transfert de données dans une forme
auto-contenue. Au sens strict, ``mashaller'' signifie convertir une
données d'une forme interne en une représentation externe (dans un
buffer RPC par exemple) et ``démarshaller'' est l'opération inverse.
- 2
- Une solution serait de refuser de tels littéraux dans l'analyseur,
puisqu'ils sont intrinsèquement non-portables. Une autre solution serait
que le module marshal déclenche une exception quand une valeur
entière est tronquée. Au moins l'une de ces solutions sera implémentée dans
une version future.
