# `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.

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 (se allow_code for verdadeiro), 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=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 por `load()`. 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 argumentos `value`, `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` ou `TypeError`. 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` com nenhum argumento.

  Nota

  Se um objeto contendo um tipo não suportado foi empacotado com `dump()`, `load()` irá substituir `None` 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 evento `marshal.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ção `ValueError` 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 argumentos `value`, `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` ou `TypeError`. 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 argumento `bytes`.

  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 evento `marshal.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

  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.