# `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. 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 bytes 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 por `load()`.

  O argumento version indica o formato de dados que o `dump` deve usar (veja abaixo).

  Levanta um evento de auditoria `marshal.dumps` com os argumentos `value`, `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` ou `TypeError`. 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á 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.

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ção `ValueError` 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 os argumentos `value`, `version`.

marshal.loads(bytes)

  Converte o objeto bytes ou similar em um valor. Se nenhum valor válido for encontrado, levanta `EOFError`, `ValueError` ou `TypeError`. Bytes extras na entrada são ignorados.

  Levanta um evento de auditoria `marshal.loads` com o 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.

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 é a 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.