marshal — Internal Python object serialization

This module contains functions that can read and write Python values in a binary format. The format is specific to Python, but independent of machine architecture issues (e.g., you can write a Python value to a file on a PC, transport the file to a Mac, and read it back there). Details of the format are undocumented on purpose; it may change between Python versions (although it rarely does). [1]

Este no es un módulo general de «persistencia». Para la persistencia general y la transferencia de objetos Python a través de llamadas RPC, consulte los módulos pickle y shelve. El módulo marshal existe principalmente para admitir la lectura y escritura del código «pseudocompilado» para los módulos Python de archivos .pyc. Por lo tanto, los mantenedores de Python se reservan el derecho de modificar el formato de cálculo de referencias de manera incompatible hacia atrás en caso de necesidad. Si va a serializar y deserializar objetos Python, utilice el módulo pickle en su lugar: el rendimiento es comparable, la independencia de la versión está garantizada y pickle admite una gama sustancialmente más amplia de objetos que marshal.

Advertencia

El módulo marshal no está destinado a ser seguro contra datos erróneos o construidos maliciosamente. Nunca deserializar con marshal los datos recibidos de una fuente no confiable o no autenticada.

Not all Python object types are supported; in general, only objects whose value is independent from a particular invocation of Python can be written and read by this module. The following types are supported: booleans, integers, floating-point numbers, complex numbers, strings, bytes, bytearrays, tuples, lists, sets, frozensets, dictionaries, and code objects, where it should be understood that tuples, lists, sets, frozensets and dictionaries are only supported as long as the values contained therein are themselves supported. The singletons None, Ellipsis and StopIteration can also be marshalled and unmarshalled. For format version lower than 3, recursive lists, sets and dictionaries cannot be written (see below).

Hay funciones que leen/escriben archivos, así como funciones que operan en objetos similares a bytes.

El módulo define estas funciones:

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

Escribe el valor en el archivo abierto. El valor debe ser un tipo admitido. El archivo debe ser un archivo binary file en el que se pueda escribir.

Si el valor tiene (o contiene un objeto que tiene) un tipo no admitido, se produce una excepción ValueError — pero los datos no utilizados también se escribirán en el archivo. El objeto no será leído correctamente por load().

El argumento version indica el formato de datos que dump debe usar (véase más adelante).

Lanza un evento de auditoría marshal.dumps con argumentos value, version.

marshal.load(file)

Lee un valor del archivo abierto y lo retorna. Si no se lee ningún valor válido (por ejemplo, porque los datos tienen un formato de cálculo de referencias incompatible de una versión de Python diferente), lanza una excepción EOFError, ValueError o TypeError. El archivo debe ser un binary file habilitado para lectura.

Lanza un evento de auditoría marshal.load sin argumentos.

Nota

Si un objeto que contiene un tipo no admitido se calcula con dump(), load() sustituirá None por el tipo «unmarshallable».

Distinto en la versión 3.10: Esta llamada solía lanzar un evento de auditoría code.__new__ para cada objeto código. Ahora lanza un único evento marshal.load para toda la operación de carga.

marshal.dumps(value[, version])

Retorna el objeto bytes que se escribiría en un archivo mediante dump(value, file). El valor debe ser un tipo admitido. Lanza una excepción ValueError si value tiene (o contiene un objeto que tiene) un tipo no admitido.

El argumento version indica el formato de datos que dumps debe usar (véase más adelante).

Lanza un evento de auditoría marshal.dumps con argumentos value, version.

marshal.loads(bytes)

Convierte el objeto bytes-like object en un valor. Si no se encuentra ningún valor válido, lanza una excepción EOFError, ValueError o TypeError. Se omiten los bytes adicionales de la entrada.

Lanza un evento de auditoría marshal.loads con argumento bytes.

Distinto en la versión 3.10: Esta llamada solía lanzar un evento de auditoría code.__new__ para cada objeto código. Ahora lanza un único evento marshal.loads para toda la operación de carga.

Además, se definen las siguientes constantes:

marshal.version

Indicates the format that the module uses. Version 0 is the historical format, version 1 shares interned strings and version 2 uses a binary format for floating-point numbers. Version 3 adds support for object instancing and recursion. The current version is 4.

Notas al pie