"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 manipuláveis com marshal; 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, conjuntos congelados, dicionários e objetos código
(se *allow_code* for verdadeiro), onde deve ser entendido que tuplas,
listas, conjuntos, conjuntos congelados e os dicionários são
suportados apenas enquanto os próprios valores contidos neles forem
suportados. Os valores únicos "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 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 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 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

   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.
