marshal
— Serialização interna de objetos Python¶
Este módulo contém funções que podem ler e gravar valores Python em formato binário. O formato é específico para Python, mas independente dos problemas de arquitetura da máquina (por exemplo, você pode gravar um valor Python em um arquivo em um PC, transportar o arquivo para um Mac e lê-lo de volta lá). Os detalhes do formato não são documentados propositalmente; ele pode mudar entre as versões do Python (embora raramente mude). [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. O formato dos objetos código não é compatível entre as versões do Python, mesmo que a versão do formato seja a mesma. Desserializar um objeto código na versão incorreta do Python tem um comportamento indefinido. 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.
Existem funções que leem/gravam arquivos, bem como funções que operam em objetos byte ou similares.
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:
Strings (
str
) andbytes
. Bytes-like objects likebytearray
are marshalled asbytes
.Containers:
tuple
,list
,set
,frozenset
, and (sinceversion
5),slice
. It should be understood that these are supported only if the values contained therein are themselves supported. Recursive containers are supported sinceversion
3.The singletons
None
,Ellipsis
andStopIteration
.code
objects, if allow_code is true. See note above about version dependence.
Alterado na versão 3.4:
Added format version 3, which supports marshalling recursive lists, sets and dictionaries.
Added format version 4, which supports efficient representations of short strings.
Alterado na versão 3.14: Added format version 5, which allows marshalling slices.
O módulo define estas funções:
- marshal.dump(value, file, version=version, /, *, allow_code=True)¶
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()
. Há suporte a objetos código somente se allow_code for verdadeiro.O argumento version indica o formato de dados que o
dump
deve usar (veja abaixo).Levanta um evento de auditoria
marshal.dumps
com os argumentosvalue
,version
.Alterado na versão 3.13: Adicionado o parâmetro allow_code.
- marshal.load(file, /, *, allow_code=True)¶
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
. Há suporte a objetos código somente se allow_code for verdadeiro. O arquivo deve ser um arquivo binário legível.Levanta um evento de auditoria
marshal.load
sem argumentos.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.Alterado na versão 3.13: Adicionado o parâmetro allow_code.
- marshal.dumps(value, version=version, /, *, allow_code=True)¶
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. Há suporte a objetos código somente se allow_code for verdadeiro.O argumento version indica o formato de dados que
dumps
deve usar (veja abaixo).Levanta um evento de auditoria
marshal.dumps
com os argumentosvalue
,version
.Alterado na versão 3.13: Adicionado o parâmetro allow_code.
- marshal.loads(bytes, /, *, allow_code=True)¶
Converte o objeto byte ou similar em um valor. Se nenhum valor válido for encontrado, levanta
EOFError
,ValueError
ouTypeError
. Há suporte a objetos código somente se allow_code for verdadeiro. Bytes extras na entrada são ignorados.Levanta um evento de auditoria
marshal.loads
com o 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.Alterado na versão 3.13: Adicionado o parâmetro allow_code.
Além disso, as seguintes constantes são definidas:
- marshal.version¶
Indicates the format that the module uses. Version 0 is the historical first version; subsequent versions add new features. Generally, a new version becomes the default when it is introduced.
Version
Available since
New features
1
Python 2.4
Sharing interned strings
2
Python 2.5
Binary representation of floats
3
Python 3.4
Support for object instancing and recursion
4
Python 3.4
Efficient representation of short strings
5
Python 3.14
Support for
slice
objects
Notas de rodapé