"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 ]-

[1] El nombre de este módulo proviene de algunos términos utilizados
    por los diseñadores de Modula-3 (entre otros), que utilizan el
    término "marshalling" para el envío de datos de forma auto-
    contenida. Estrictamente hablando "marshalling", significa
    convertir algunos datos internos en un formato externo (por
    ejemplo, en un búfer RPC) y "unmarshalling" es el proceso inverso.
