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

## Uso na linha de comando

Adicionado 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 serializado em pickle ao invés dos detalhes do formato pickle, você pode usar `-m pickle`. No entanto, quando o arquivo serializado em 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

### 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 serializado em pickle for especificado, imprime o preâmbulo fornecido antes de cada desmontagem.

## 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árias serializações com pickle criadas 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.

  Alterado na versão 3.2: Adicionado o parâmetro annotate.

pickletools.genops(pickle)

  Fornece um iterador sobre todos os códigos de operação em uma serialização com 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.