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 não é um módulo de “persistência” geral. Para persistência geral e transferência de objetos Python através de chamadas RPC, veja os módulos pickle
e shelve
. O módulo marshal
existe principalmente para ter suporte à leitura e escrita do código “pseudocompilado” para módulos Python de arquivos .pyc
. Portanto, os mantenedores do Python se reservam o direito de modificar o formato do marshal de maneiras incompatíveis com versões anteriores, caso seja necessário. Se você estiver serializando e desserializando objetos Python, use o módulo pickle
– o desempenho é comparável, a independência de versão é garantida e pickle tem suporte a uma gama substancialmente maior de objetos do que marshal.
Aviso
O módulo marshal
não se destina a ser seguro contra dados errôneos ou construídos de forma maliciosa. Nunca faça o unmarshalling de dados recebidos de uma fonte não confiável ou não 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).
Existem funções que leem/gravam arquivos, bem como funções que operam em objetos byte ou similares.
O módulo define estas funções:
- marshal.dump(value, file[, version])¶
Grava o valor no arquivo aberto. O valor deve ser um tipo compatível. O arquivo deve ser arquivo binário gravável.
Se o valor tem (ou contém um objeto que tem) um tipo não suportado, uma exceção
ValueError
é levantada – mas dados de lixo também serão gravados no arquivo. O objeto não será lido corretamente porload()
.O argumento version indica o formato de dados que o
dump
deve usar (veja abaixo).Levanta um evento de auditoria
marshal.dumps
com argumentosvalue
,version
.
- marshal.load(file)¶
Lê um valor do arquivo aberto e retorna-o. Se nenhum valor válido for lido (por exemplo, porque os dados têm um formato de empacotamento incompatível com uma versão diferente do Python), levanta
EOFError
,ValueError
ouTypeError
. O arquivo deve ser um arquivo binário legível.Levanta um evento de auditoria
marshal.load
com nenhum argumento.Nota
Se um objeto contendo um tipo não suportado foi empacotado com
dump()
,load()
irá substituirNone
pelo tipo não empacotável.Alterado na versão 3.10: Esta chamada costumava levantar um evento de auditoria
code.__new__
para cada objeto código. Agora, ele levanta um único eventomarshal.load
para toda a operação de carregamento.
- marshal.dumps(value[, version])¶
Retorna o objeto bytes que seria escrito em um arquivo por
dump(value, file)
. O valor deve ser um tipo compatível. Levanta uma exceçãoValueError
se o valor tem (ou contém um objeto que tem) um tipo não suportado.O argumento version indica o formato de dados que
dumps
deve usar (veja abaixo).Levanta um evento de auditoria
marshal.dumps
com argumentosvalue
,version
.
- marshal.loads(bytes)¶
Converte o objeto byte ou similar em um valor. Se nenhum valor válido for encontrado, levanta
EOFError
,ValueError
ouTypeError
. Bytes extras na entrada são ignorados.Levanta um evento de auditoria
marshal.loads
com argumentobytes
.Alterado na versão 3.10: Esta chamada costumava levantar um evento de auditoria
code.__new__
para cada objeto código. Agora, ele levanta um único eventomarshal.loads
para toda a operação de carregamento.
Além disso, as seguintes constantes são definidas:
- 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 de rodapé