Документация Python неофициальный перевод
Содержание страницы

32.12. dis – Дизассемблер байт-кода Pythondis – Disassembler for Python bytecode

Исходный код: Lib/dis.py


Модуль dis позволяет анализировать байт-код CPython, дизассемблируя его. Байт-код CPython, который этот модуль принимает на вход, определён в файле Include/opcode.h и используется компилятором и интерпретатором.

Особенность реализации CPython: Байт-код является деталью реализации интерпретатора CPython. Нет никаких гарантий, что байт-код не будет добавлен, удалён или изменён в разных версиях Python. Не следует рассчитывать, что использование этого модуля будет работать в разных виртуальных машинах Python или в разных релизах Python.

Пример: дана функция myfunc():

def myfunc(alist):
    return len(alist)

следующая команда позволяет вывести дизассемблированный код myfunc():

>>> dis.dis(myfunc)
  2           0 LOAD_GLOBAL              0 (len)
              3 LOAD_FAST                0 (alist)
              6 CALL_FUNCTION            1
              9 RETURN_VALUE

(«2» – это номер строки).

32.12.1. Анализ байткодаBytecode analysis

Новое в версии 3.4.

API анализа байт-кода позволяет оборачивать фрагменты кода Python в объект Bytecode, который предоставляет простой доступ к деталям скомпилированного кода.

class dis.Bytecode(x, *, first_line=None, current_offset=None)

Анализирует байт-код, соответствующий функции, методу, строке исходного кода или объекту кода (возвращаемому функцией compile()).

Это удобная обёртка над многими из перечисленных ниже функций, в первую очередь get_instructions(): при итерации по экземпляру Bytecode возвращаются операции байт-кода в виде экземпляров Instruction.

Если first_line не равен None, он указывает номер строки, который должен отображаться для первой строки исходного кода в дизассемблированном коде. В противном случае информация о строках исходного кода (если она есть) берётся непосредственно из дизассемблированного объекта кода.

Если current_offset не равен None, он задаёт смещение инструкции в дизассемблированном коде. Установка этого параметра означает, что dis() будет отображать маркер “current instruction” рядом с указанным опкодом.

classmethod from_traceback(tb)

Создаёт экземпляр Bytecode из заданной трассировки, устанавливая current_offset на инструкцию, вызвавшую исключение.

codeobj

Скомпилированный объект кода.

first_line

Первая строка исходного кода объекта кода (если доступна)

dis()

Возвращает отформатированное представление операций байт-кода (то же, что печатается функцией dis.dis(), но возвращается в виде многострочной строки).

info()

Возвращает отформатированную многострочную строку с подробной информацией об объекте кода, как code_info().

Пример:

>>> bytecode = dis.Bytecode(myfunc)
>>> for instr in bytecode:
...     print(instr.opname)
...
LOAD_GLOBAL
LOAD_FAST
CALL_FUNCTION
RETURN_VALUE

32.12.2. Функции анализаAnalysis functions

Модуль dis также определяет следующие функции анализа, которые преобразуют входные данные напрямую в нужный результат. Они могут быть полезны, если выполняется только одна операция и промежуточный объект анализа не нужен:

dis.code_info(x)

Возвращает отформатированную многострочную строку с подробной информацией об объекте кода для указанной функции, метода, строки исходного кода или объекта кода.

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

Новое в версии 3.2.

dis.show_code(x, *, file=None)

Выводит подробную информацию об объекте кода для указанной функции, метода, строки исходного кода или объекта кода в file (или в sys.stdout, если file не указан).

Это удобная краткая запись для print(code_info(x), file=file), предназначенная для интерактивного исследования в приглашении интерпретатора.

Новое в версии 3.2.

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

dis.dis(x=None, *, file=None)

Дизассемблирует объект x. x может обозначать модуль, класс, метод, функцию, объект кода, строку исходного кода или последовательность байтов сырого байт-кода. Для модуля дизассемблируются все функции. Для класса – все методы. Для объекта кода или последовательности сырого байт-кода выводится по одной строке на каждую инструкцию байт-кода. Строки сначала компилируются в объекты кода с помощью встроенной функции compile(), а затем дизассемблируются. Если объект не указан, функция дизассемблирует последнюю трассировку.

Результат дизассемблирования выводится в виде текста в указанный аргумент file, если он задан, иначе в sys.stdout.

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

dis.distb(tb=None, *, file=None)

Дисассемблирует функцию, находящуюся на вершине стека traceback; если traceback не передан, используется последний. Указывается инструкция, вызвавшая исключение.

Результат дизассемблирования выводится в виде текста в указанный аргумент file, если он задан, иначе в sys.stdout.

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

dis.disassemble(code, lasti=-1, *, file=None)
dis.disco(code, lasti=-1, *, file=None)

Дисассемблирует объект кода, указывая последнюю инструкцию, если передан lasti. Результат разбит на следующие столбцы:

  1. номер строки для первой инструкции каждой строки
  2. текущая инструкция, помечена как -->,
  3. инструкция с меткой, помечена >>,
  4. адрес инструкции,
  5. название кода операции,
  6. параметры операции и
  7. интерпретация параметров в скобках.

Интерпретация параметров распознаёт имена локальных и глобальных переменных, константные значения, цели переходов и операторы сравнения.

Дизассемблированный код выводится в виде текста в аргумент file, если он указан, иначе – в sys.stdout.

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

dis.get_instructions(x, *, first_line=None)

Возвращает итератор по инструкциям в переданной функции, методе, строке исходного кода или объекте кода.

Итератор генерирует последовательность именованных кортежей Instruction, содержащих подробности каждой операции в переданном коде.

Если first_line не равен None, он указывает номер строки, который должен отображаться для первой строки исходного кода в дизассемблированном коде. В противном случае информация о строках исходного кода (если она есть) берётся непосредственно из объекта дизассемблированного кода.

Новое в версии 3.4.

dis.findlinestarts(code)

Эта функция-генератор использует атрибуты co_firstlineno и co_lnotab объекта кода code для поиска смещений, соответствующих началам строк в исходном коде. Они генерируются в виде пар (offset, lineno).

dis.findlabels(code)

Определяет все смещения в объекте кода code, которые являются целями перехода, и\nвозвращает список этих смещений.

dis.stack_effect(opcode[, oparg])

Вычисляет эффект стека для opcode с аргументом oparg.

Новое в версии 3.4.

32.12.3. Инструкции байткода PythonPython Bytecode Instructions

Функция get_instructions() и класс Bytecode предоставляют подробную информацию об инструкциях байт-кода в виде экземпляров Instruction:

class dis.Instruction

Подробности об операции байткода

opcode

Числовой код операции, соответствующий значениям опкодов, перечисленным ниже, и значениям байткода в коллекциях Opcode.

opname

Человекочитаемое имя операции

arg

числовой аргумент операции (если есть), иначе None

argval

разрешённое значение аргумента (если известно), иначе то же, что и arg

argrepr

человекочитаемое описание аргумента операции

offset

начальный индекс операции в последовательности байт-кода

starts_line

строка, начинающаяся с этой операции (если есть), иначе None

is_jump_target

True, если другой код переходит сюда, иначе False

Новое в версии 3.4.

В настоящее время компилятор Python генерирует следующие инструкции байткода.

Общие инструкции

NOP

Код, который ничего не делает. Используется в качестве заполнителя оптимизатором байт-кода.

POP_TOP

Удаляет элемент с вершины стека (TOS).

ROT_TWO

Меняет местами два верхних элемента стека.

ROT_THREE

Поднимает второй и третий элементы стека на одну позицию вверх, перемещает верхний вниз на третью позицию.

DUP_TOP

Дублирует ссылку на вершине стека.

DUP_TOP_TWO

Дублирует две ссылки на вершине стека, сохраняя их порядок.

Унарные операции

Унарные операции берут элемент с вершины стека, применяют операцию и помещают результат обратно на стек.

UNARY_POSITIVE

Реализует TOS = +TOS.

UNARY_NEGATIVE

Реализует TOS = -TOS.

UNARY_NOT

Реализует TOS = не TOS.

UNARY_INVERT

Реализует TOS = ~TOS.

GET_ITER

Реализует TOS = iter(TOS).

Бинарные операции

Бинарные операции удаляют из стека элемент с вершины (TOS) и второй сверху элемент стека (TOS1). Они выполняют операцию и помещают результат обратно в стек.

BINARY_POWER

Реализует TOS = TOS1 ** TOS.

BINARY_MULTIPLY

Реализует TOS = TOS1 * TOS.

BINARY_FLOOR_DIVIDE

Реализует TOS = TOS1 // TOS.

BINARY_TRUE_DIVIDE

Реализует TOS = TOS1 / TOS.

BINARY_MODULO

Реализует TOS = TOS1 % TOS.

BINARY_ADD

Реализует TOS = TOS1 + TOS.

BINARY_SUBTRACT

Реализует TOS = TOS1 - TOS.

BINARY_SUBSCR

Реализует TOS = TOS1[TOS].

BINARY_LSHIFT

Реализует TOS = TOS1 << TOS.

BINARY_RSHIFT

Реализует TOS = TOS1 >> TOS.

BINARY_AND

Реализует TOS = TOS1 & TOS.

BINARY_XOR

Реализует TOS = TOS1 ^ TOS.

BINARY_OR

Реализует TOS = TOS1 | TOS.

Операции на месте

Операции на месте аналогичны бинарным: они также удаляют TOS и TOS1 и помещают результат обратно в стек, но операция выполняется на месте, если TOS1 это поддерживает, и результирующий TOS может (но не обязан) быть исходным TOS1.

INPLACE_POWER

Реализует in-place: TOS = TOS1 ** TOS.

INPLACE_MULTIPLY

Реализует in-place: TOS = TOS1 * TOS.

INPLACE_FLOOR_DIVIDE

Реализует in-place: TOS = TOS1 // TOS.

INPLACE_TRUE_DIVIDE

Реализует in-place: TOS = TOS1 / TOS.

INPLACE_MODULO

Реализует in-place: TOS = TOS1 % TOS.

INPLACE_ADD

Реализует in-place: TOS = TOS1 + TOS.

INPLACE_SUBTRACT

Реализует in-place: TOS = TOS1 - TOS.

INPLACE_LSHIFT

Реализует in-place: TOS = TOS1 << TOS.

INPLACE_RSHIFT

Реализует in-place: TOS = TOS1 >> TOS.

INPLACE_AND

Реализует in-place: TOS = TOS1 & TOS.

INPLACE_XOR

Реализует in-place: TOS = TOS1 ^ TOS.

INPLACE_OR

Реализует in-place: TOS = TOS1 | TOS.

STORE_SUBSCR

Реализует TOS1[TOS] = TOS2.

DELETE_SUBSCR

Реализует del TOS1[TOS].

Прочие опкоды

PRINT_EXPR

Реализует инструкцию выражения для интерактивного режима. TOS удаляется из стека и выводится. В неинтерактивном режиме инструкция выражения завершается POP_TOP.

BREAK_LOOP

Завершает цикл при выполнении оператора break.

CONTINUE_LOOP(target)

Продолжает цикл из-за оператора continue. target – это адрес, на который нужно перейти (должен быть инструкцией FOR_ITER).

SET_ADD(i)

Вызывает set.add(TOS1[-i], TOS). Используется для реализации множественных включений (set comprehensions).

LIST_APPEND(i)

Вызывает list.append(TOS[-i], TOS). Используется для реализации списковых включений (list comprehensions).

MAP_ADD(i)

Вызывает dict.setitem(TOS1[-i], TOS, TOS1). Используется для реализации словарных включений (dict comprehensions).

Для всех инструкций SET_ADD, LIST_APPEND и MAP_ADD: после извлечения добавленного значения или пары ключ/значение объект-контейнер остаётся в стеке, чтобы быть доступным для следующих итераций цикла.

RETURN_VALUE

Возвращает TOS вызывающей стороне функции.

YIELD_VALUE

Извлекает TOS и возвращает его из генератора.

YIELD_FROM

Извлекает TOS и делегирует ему как под-итератор от генератора.

Новое в версии 3.3.

IMPORT_STAR

Загружает все символы, не начинающиеся с '_', из модуля TOS напрямую в локальное пространство имён. Модуль извлекается после загрузки всех имён. Эта опкод реализует from module import *.

POP_BLOCK

Удаляет один блок из стека блоков. В каждом фрейме есть стек блоков, представляющий вложенные циклы, операторы try и т.п.

POP_EXCEPT

Удаляет один блок из стека блоков. Извлечённый блок должен быть блоком обработчика исключения, неявно создаваемым при входе в обработчик except. Помимо извлечения лишних значений из стека фрейма, последние три извлечённых значения используются для восстановления состояния исключения.

END_FINALLY

Завершает блок finally. Интерпретатор запоминает, нужно ли повторно возбуждать исключение или функция возвращается, и продолжает со следующим внешним блоком.

LOAD_BUILD_CLASS

Помещает builtins.__build_class__() в стек. Позже он вызывается с помощью CALL_FUNCTION для создания класса.

SETUP_WITH(delta)

Эта опкод выполняет несколько операций перед началом блока with. Сначала загружается __exit__() из менеджера контекста и помещается в стек для последующего использования WITH_CLEANUP. Затем вызывается __enter__(), и помещается блок finally, указывающий на delta. Наконец, результат вызова метода enter помещается в стек. Следующая опкод либо игнорирует его (POP_TOP), либо сохраняет в переменную (STORE_FAST, STORE_NAME или UNPACK_SEQUENCE).

WITH_CLEANUP

Очищает стек при завершении блока оператора with. TOS – это привязанный метод менеджера контекста __exit__(). Под TOS находятся 1–3 значения, указывающие, как/почему был введён блок finally:

  • SECOND = None
  • (SECOND, THIRD) = (WHY_{RETURN,CONTINUE}), retval
  • SECOND = WHY_*; под ним нет retval
  • (SECOND, THIRD, FOURTH) = exc_info()

В последнем случае вызывается TOS(SECOND, THIRD, FOURTH), иначе TOS(None, None, None). Кроме того, TOS удаляется из стека.

Если стек представляет исключение и вызов функции возвращает «истинное» значение, эта информация «обнуляется» и заменяется одним WHY_SILENCED, чтобы предотвратить повторное возбуждение исключения через END_FINALLY. (Но нелокальные goto всё равно будут возобновлены.)

Все следующие опкоды требуют аргументов. Аргумент занимает два байта, причём старший байт идёт последним.

STORE_NAME(namei)

Реализует name = TOS. namei – это индекс name в атрибуте co_names объекта кода. Компилятор старается использовать STORE_FAST или STORE_GLOBAL, если это возможно.

DELETE_NAME(namei)

Реализует del name, где namei – это индекс в атрибуте co_names объекта кода.

UNPACK_SEQUENCE(count)

Распаковывает TOS в count отдельных значений, которые помещаются в стек справа налево.

UNPACK_EX(counts)

Реализует присваивание с целевой переменной со звёздочкой: распаковывает итерируемый объект в TOS в отдельные значения, где общее количество значений может быть меньше количества элементов в итерируемом объекте: одно из новых значений будет списком всех оставшихся элементов.

Младший байт counts – это количество значений до спискового значения, а старший байт counts – количество значений после него. Результирующие значения помещаются в стек справа налево.

STORE_ATTR(namei)

Реализует TOS.name = TOS1, где namei – это индекс имени в co_names.

DELETE_ATTR(namei)

Реализует del TOS.name, используя namei как индекс в co_names.

STORE_GLOBAL(namei)

Работает как STORE_NAME, но сохраняет имя как глобальное.

DELETE_GLOBAL(namei)

Работает как DELETE_NAME, но удаляет глобальное имя.

LOAD_CONST(consti)

Помещает co_consts[consti] в стек.

LOAD_NAME(namei)

Помещает значение, связанное с co_names[namei], в стек.

BUILD_TUPLE(count)

Создаёт кортеж, потребляя count элементов из стека, и помещает полученный кортеж в стек.

BUILD_LIST(count)

Работает как BUILD_TUPLE, но создаёт список.

BUILD_SET(count)

Работает как BUILD_TUPLE, но создаёт множество.

BUILD_MAP(count)

Помещает новый объект словаря в стек. Словарь предварительно настраивается на хранение count записей.

LOAD_ATTR(namei)

Заменяет TOS на getattr(TOS, co_names[namei]).

COMPARE_OP(opname)

Выполняет булеву операцию. Имя операции можно найти в cmp_op[opname].

IMPORT_NAME(namei)

Импортирует модуль co_names[namei]. TOS и TOS1 извлекаются и предоставляют аргументы fromlist и level функции __import__(). Объект модуля помещается в стек. Текущее пространство имён не затрагивается: для правильной инструкции импорта последующая инструкция STORE_FAST изменяет пространство имён.

IMPORT_FROM(namei)

Загружает атрибут co_names[namei] из модуля, находящегося в TOS. Полученный объект помещается в стек для последующего сохранения инструкцией STORE_FAST.

JUMP_FORWARD(delta)

Увеличивает счётчик байт-кода на delta.

POP_JUMP_IF_TRUE(target)

Если TOS истинно, устанавливает счётчик байткода в target. TOS извлекается из стека.

POP_JUMP_IF_FALSE(target)

Если TOS ложно, устанавливает счётчик байткода в target. TOS извлекается из стека.

JUMP_IF_TRUE_OR_POP(target)

Если TOS истинно, устанавливает счётчик байткода в target и оставляет TOS на стеке. В противном случае (TOS ложно) TOS извлекается.

JUMP_IF_FALSE_OR_POP(target)

Если TOS ложно, устанавливает счётчик байткода в target и оставляет TOS на стеке. В противном случае (TOS истинно) TOS извлекается.

JUMP_ABSOLUTE(target)

Устанавливает счётчик байткода в target.

FOR_ITER(delta)

TOS – это итератор. Вызвать его метод __next__(). Если он возвращает новое значение, поместить его в стек (оставив итератор под ним). Если итератор сообщает, что он исчерпан, TOS извлекается, а счётчик байт-кода увеличивается на delta.

LOAD_GLOBAL(namei)

Загружает глобальную переменную с именем co_names[namei] в стек.

SETUP_LOOP(delta)

Помещает блок для цикла в стек блоков. Блок начинается с текущей инструкции и имеет размер delta байт.

SETUP_EXCEPT(delta)

Помещает блок try из конструкции try-except в стек блоков. delta указывает на первый блок except.

SETUP_FINALLY(delta)

Pushes a try block from a try-except clause onto the block stack. delta points to the finally block.

STORE_MAP

Сохраняет пару ключ-значение в словаре. Извлекает ключ и значение, оставляя словарь в стеке.

LOAD_FAST(var_num)

Помещает ссылку на локальную переменную co_varnames[var_num] в стек.

STORE_FAST(var_num)

Сохраняет TOS в локальную переменную co_varnames[var_num].

DELETE_FAST(var_num)

Удаляет локальную переменную co_varnames[var_num].

LOAD_CLOSURE(i)

Помещает ссылку на ячейку, содержащуюся в слоте i хранилища ячеек и свободных переменных. Имя переменной – co_cellvars[i], если i меньше длины co_cellvars. В противном случае это co_freevars[i - len(co_cellvars)].

LOAD_DEREF(i)

Загружает ячейку, содержащуюся в слоте i хранилища ячеек и свободных переменных. Помещает ссылку на объект, который содержит ячейка, в стек.

LOAD_CLASSDEREF(i)

Работает почти как LOAD_DEREF, но сначала проверяет словарь locals, прежде чем обращаться к ячейке. Это используется для загрузки свободных переменных в телах классов.

STORE_DEREF(i)

Сохраняет TOS в ячейку, содержащуюся в слоте i хранилища ячеек и свободных переменных.

DELETE_DEREF(i)

Опустошает ячейку, содержащуюся в слоте i хранилища ячеек и свободных переменных. Используется оператором del.

RAISE_VARARGS(argc)

Вызывает исключение. argc указывает количество параметров оператора raise (от 0 до 3). Обработчик увидит объект traceback как TOS2, параметр как TOS1, а исключение как TOS.

CALL_FUNCTION(argc)

Вызывает функцию. Младший байт argc указывает количество позиционных параметров, старший байт – количество именованных параметров. В стеке опкод сначала находит именованные параметры. Для каждого именованного аргумента значение находится над ключом. Под именованными параметрами в стеке находятся позиционные параметры, при этом самый правый параметр сверху. Под параметрами в стеке находится вызываемый объект функции. Извлекает все аргументы функции и саму функцию из стека и помещает возвращаемое значение.

MAKE_FUNCTION(argc)

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

  • argc & 0xFF объекты аргументов по умолчанию в позиционном порядке.
  • (argc >> 8) & 0xFF пары имя и аргумент по умолчанию, причём имя находится непосредственно под объектом в стеке, для параметров только по ключевым словам
  • (argc >> 16) & 0x7FFF объекты аннотаций параметров
  • кортеж, перечисляющий имена параметров для аннотаций (только если есть хотя бы один объект аннотации)
  • код, связанный с функцией (на TOS1)
  • полное имя функции (на TOS)
MAKE_CLOSURE(argc)

Создаёт новый объект функции, устанавливает его слот __closure__ и помещает его в стек. TOS – это полное имя функции, TOS1 – это код, связанный с функцией, а TOS2 – это кортеж, содержащий ячейки для свободных переменных замыкания. argc интерпретируется так же, как в MAKE_FUNCTION; аннотации и значения по умолчанию также находятся в том же порядке ниже TOS2.

BUILD_SLICE(argc)

Помещает объект среза в стек. argc должен быть равен 2 или 3. Если он равен 2, помещается slice(TOS1, TOS); если 3 – slice(TOS2, TOS1, TOS). Подробнее см. встроенную функцию slice().

EXTENDED_ARG(ext)

Добавляет префикс к любой опкоду, чей аргумент слишком велик, чтобы поместиться в стандартные два байта. ext содержит два дополнительных байта, которые вместе с аргументом последующего опкода образуют четырёхбайтовый аргумент, причём ext является двумя старшими байтами.

CALL_FUNCTION_VAR(argc)

Вызывает функцию. argc интерпретируется так же, как в CALL_FUNCTION. На вершине стека находится список с переменным количеством аргументов, за которым следуют ключевые и позиционные аргументы.

CALL_FUNCTION_KW(argc)

Вызывает функцию. argc интерпретируется так же, как в CALL_FUNCTION. На вершине стека находится словарь ключевых аргументов, за которым следуют явные ключевые и позиционные аргументы.

CALL_FUNCTION_VAR_KW(argc)

Вызывает функцию. argc интерпретируется так же, как в CALL_FUNCTION. На вершине стека находится словарь ключевых аргументов, за которым следует кортеж аргументов переменной длины, а затем явные ключевые и позиционные аргументы.

HAVE_ARGUMENT

Это на самом деле не опкод. Он определяет разделительную линию между опкодами, которые не принимают аргументы < HAVE_ARGUMENT, и теми, которые принимают >= HAVE_ARGUMENT.

32.12.4. Коллекции опкодовOpcode collections

Эти коллекции предоставляются для автоматического самоанализа инструкций байткода:

dis.opname

Последовательность имён операций, индексируемая с помощью байткода.

dis.opmap

Словарь, сопоставляющий имена операций с байткодами.

dis.cmp_op

Последовательность всех имён операций сравнения.

dis.hasconst

Последовательность байткодов, имеющих постоянный параметр.

dis.hasfree

Последовательность байткодов, которые обращаются к свободной переменной (обратите внимание, что «free» в данном контексте относится к именам в текущей области видимости, на которые ссылаются внутренние области видимости, или к именам во внешних областях видимости, на которые ссылаются из этой области. Она не включает ссылки на глобальные или встроенные области видимости).

dis.hasname

Последовательность байткодов, обращающихся к атрибуту по имени.

dis.hasjrel

Последовательность байткодов, имеющих относительную цель перехода.

dis.hasjabs

Последовательность байткодов, имеющих абсолютную цель перехода.

dis.haslocal

Последовательность байткодов, обращающихся к локальной переменной.

dis.hascompare

Последовательность байткодов логических операций.