32.13. "pickletools" --- Ferramentas para desenvolvedores pickle
****************************************************************

**Código Fonte:** Lib/pickletools.py

======================================================================

Este módulo contém várias constantes relacionadas aos detalhes íntimos
do módulo "pickle", alguns comentários extensos sobre a implementação
e algumas funções úteis para analisar dados em conserva. O conteúdo
deste módulo é útil para desenvolvedores do núcleo Python que estão
trabalhando no "pickle"; usuários comuns do módulo "pickle"
provavelmente não acharão o módulo "pickletools" relevante.


32.13.1. Uso na linha de comando
================================

Novo na versão 3.2.

Quando chamado a partir da linha de comando, "python -m pickletools"
irá desmontar o conteúdo de um ou mais arquivos pickle. Note que se
você quiser ver o objeto Python armazenado no pickle ao invés dos
detalhes do formato pickle, você pode usar "-m pickle". No entanto,
quando o arquivo pickle que você deseja examinar vem de uma fonte não
confiável, "-m pickletools" é uma opção mais segura porque não executa
bytecode pickle.

Por exemplo, com uma tupla "(1, 2)" tratada com pickling no arquivo
"x.pickle":

   $ python -m pickle x.pickle
   (1, 2)

   $ python -m pickletools x.pickle
       0: \x80 PROTO      3
       2: K    BININT1    1
       4: K    BININT1    2
       6: \x86 TUPLE2
       7: q    BINPUT     0
       9: .    STOP
   highest protocol among opcodes = 2


32.13.1.1. Opções da linha de comando
-------------------------------------

-a, --annotate

   Anota cada linha com uma descrição curta do código de operação.

-o, --output=<file>

   Nome de um arquivo no qual a saída deve ser escrita.

-l, --indentlevel=<num>

   O número de espaços em branco para indentar um novo nível MARK.

-m, --memo

   Quando vários objetos são desmontados, preserva memo entre as
   desmontagens.

-p, --preamble=<preamble>

   Quando mais de um arquivo pickle for especificado, imprime o
   preâmbulo fornecido antes de cada desmontagem.


32.13.2. Interface programática
===============================

pickletools.dis(pickle, out=None, memo=None, indentlevel=4, annotate=0)

   Produz uma desmontagem simbólica do pickle para o objeto arquivo ou
   similar *out*, tendo como padrão "sys.stdout". *pickle* pode ser
   uma string ou um objeto arquivo ou similar. *memo* pode ser um
   dicionário Python que será usado como memo do pickle; ele pode ser
   usado para realizar desmontagens em vários pickles criados pelo
   mesmo pickler. Níveis sucessivos, indicados por códigos de operação
   "MARK" no fluxo, são indentados por espaços *indentlevel*. Se um
   valor diferente de zero for fornecido para *annotate*, cada código
   de operação na saída será anotado com uma breve descrição. O valor
   de *annotate* é usado como uma dica para a coluna onde a anotação
   deve começar.

   Novo na versão 3.2: O argumento *annotate*.

pickletools.genops(pickle)

   Fornece um *iterador* sobre todos os códigos de operação em um
   pickle, retornando uma sequência de triplos "(opcode, arg, pos)".
   *opcode* é uma instância de uma classe "OpcodeInfo"; *arg* é o
   valor decodificado, como um objeto Python, do argumento do opcode;
   *pos* é a posição em que este código de operação está localizado.
   *pickle* pode ser uma string ou um objeto arquivo ou similar.

pickletools.optimize(picklestring)

   Retorna uma nova string pickle equivalente após eliminar códigos de
   operação "PUT" não utilizados. O pickle otimizado é mais curto,
   leva menos tempo de transmissão, requer menos espaço de
   armazenamento e efetua unpickling com mais eficiência.
