# `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 bytes 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:

- Numeric types: `int`, `bool`, `float`, `complex`.

- Strings (`str`) and `bytes`. Bytes-like objects like `bytearray` are marshalled as `bytes`.

- Containers: `tuple`, `list`, `set`, `frozenset`, and (since `version` 5), `slice`. It should be understood that these are supported only if the values contained therein are themselves supported. Recursive containers are supported since `version` 3.

- The singletons `None`, `Ellipsis` and `StopIteration`.

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

  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 os argumentos `value`, `version`.

  Alterado na versão 3.13: Adicionado o parâmetro allow_code.

marshal.loads(bytes, /, *, allow_code=True)

  Converte o objeto bytes 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 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.

  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.

  Versão | Available since | Novas funcionalidades
  --- | --- | ---
  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é

[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.