12.4. 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).
-
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.
-
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).
-
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.
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.