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 Sun 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. 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.
Nem todos os tipos de objetos Python são suportados; em geral, apenas objetos cujo valor é independente de uma invocação particular de Python podem ser escritos e lidos por este módulo. Os seguintes tipos são suportados: booleanos, inteiros, números de ponto flutuante, números complexos, strings, bytes, bytearrays, tuplas, listas, conjuntos, frozensets, dicionários e objetos código, onde deve ser entendido que tuplas, listas, conjuntos, frozensets e os dicionários são suportados apenas enquanto os próprios valores contidos neles forem suportados. Os singletons None
, Ellipsis
e StopIteration
também podem ser serializados e dessarializados com marshal. Para formato version inferior a 3, listas recursivas, conjuntos e dicionários não podem ser escritos (veja abaixo).
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).Raises an auditing event
marshal.dumps
with argumentsvalue
,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.Raises an auditing event
marshal.load
with no arguments.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.9.7: This call used to raise a
code.__new__
audit event for each code object. Now it raises a singlemarshal.load
event for the entire load operation.
-
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).Raises an auditing event
marshal.dumps
with argumentsvalue
,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.Raises an auditing event
marshal.loads
with argumentbytes
.Alterado na versão 3.9.7: This call used to raise a
code.__new__
audit event for each code object. Now it raises a singlemarshal.loads
event for the entire load operation.
Além disso, as seguintes constantes são definidas:
-
marshal.
version
¶ Indica o formato que o módulo usa. A versão 0 é o formato histórico, a versão 1 compartilha strings internas e a versão 2 usa um formato binário para números de ponto flutuante. A versão 3 adiciona suporte para instanciação e recursão de objetos. A versão atual é 4.
Notas de rodapé
- 1
O nome deste módulo deriva de um pouco da terminologia usada pelos designers do Modula-3 (entre outros), que usam o termo “marshalling” para enviar dados em um formato independente. Estritamente falando, “to marshal” significa converter alguns dados da forma interna para a externa (em um buffer RPC, por exemplo) e “unmarshalling” para o processo reverso.