pickletools — Инструменты для разработчиков маринованных огурцов

Источник: Lib/pickletools.py

Этот модуль содержит различные константы, относящиеся к интимным деталям модуля pickle, несколько пространных комментариев о реализации, а также несколько полезных функций для анализа маринованных данных. Содержание этого модуля полезно для разработчиков ядра Python, которые работают над модулем pickle; обычные пользователи модуля pickle, вероятно, не найдут модуль pickletools актуальным.

Использование командной строки

Added in version 3.2.

При вызове из командной строки python -m pickletools разбирает содержимое одного или нескольких файлов pickle. Обратите внимание, что если вы хотите увидеть объект Python, хранящийся в pickle, а не детали формата pickle, то лучше использовать -m pickle. Однако если файл pickle, который вы хотите изучить, получен из ненадежного источника, -m pickletools - более безопасный вариант, поскольку он не выполняет байткод pickle.

Например, с кортежем (1, 2), маринованным в файле 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

Параметры командной строки

-a, --annotate

Аннотируйте каждую строку коротким описанием опкода.

-o, --output=<file>

Имя файла, в который должен быть записан вывод.

-l, --indentlevel=<num>

Количество пробелов, на которое нужно сделать отступ для нового уровня MARK.

-m, --memo

При разборке нескольких объектов сохраняйте памятки между разборками.

-p, --preamble=<preamble>

Если задано несколько pickle-файлов, перед каждой разборкой выводите заданную преамбулу.

Программный интерфейс

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

Выводит символическую разборку pickle в файлоподобный объект out, по умолчанию в sys.stdout. pickle может быть строкой или файлоподобным объектом. memo может быть словарем Python, который будет использоваться в качестве мемо для пикля; он может использоваться для выполнения дизассемблирования нескольких пиклей, созданных одним и тем же пиклером. Последовательные уровни, обозначенные MARK опкодами в потоке, отступают на indentlevel пробелов. Если для параметра annotate задано ненулевое значение, каждый опкод в выводе аннотируется кратким описанием. Значение annotate используется как подсказка для столбца, с которого должна начинаться аннотация.

Изменено в версии 3.2: Добавлен параметр annotate.

pickletools.genops(pickle)

Обеспечивает iterator над всеми опкодами в pickle, возвращая последовательность (opcode, arg, pos) троек. opcode - это экземпляр класса OpcodeInfo; arg - это декодированное значение аргумента опкода в виде объекта Python; pos - это позиция, в которой находится данный опкод. pickle может быть строкой или файлоподобным объектом.

pickletools.optimize(picklestring)

Возвращает новую эквивалентную строку pickle после удаления неиспользуемых PUT опкодов. Оптимизированный pickle короче, занимает меньше времени при передаче, требует меньше места для хранения и распаковывается более эффективно.