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 por
   "load()".

   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" ou "TypeError". O arquivo deve ser
   um *arquivo binário* legível.

   Nota:

     Se um objeto contendo um tipo não suportado foi empacotado com
     "dump()", "load()" irá substituir "None" pelo tipo não
     empacotá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çã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).

marshal.loads(bytes)

   Converte o *objeto byte ou similar* em um valor. Se nenhum valor
   válido for encontrado, levanta "EOFError", "ValueError" ou
   "TypeError". 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.
