inspect — Инспекция “живых” объектов

New in version 2.1.

Source code: :source:`Lib/inspect.py`


Модуль inspect предоставляет множество полезных функций, которые помогают Вам получить информацию о “живых” объектах, таких как модули, классы, методы, функции, трассировка, объекты фрейма и кода. Например, он может помочь Вам проверить контекст класса, получить исходный код метода, извлечь и отформатировать список аргументов для функции, или получить всю информацию, которая Вам нужна для отображения подробной трассировки.

Есть четыре основных вида сервисов, предоставляемых этим модулем: проверка типа, получение исходного кода, инспекция классов и функций, и проверка стэка интерпретатора.

Типы и члены

Функция getmembers() получает члены объекта, такого как класс или модуль. Шестнадцать функций, чьи имена начинаются с “is” в основном являются подходящим выбором в качестве второго аргумента для getmembers(). Кроме того, они помогают Вам определить, когда Вы можете ожидать обнаружить следующие специальные атрибуты:

Тип Атрибут Описание Примечание
module __doc__ строка документации  
  __file__ имя файла (отсутствует для встроенных модулей)  
class __doc__ строка документации  
  __module__ имя модуля в котором определён этот класс  
method __doc__ строка документации  
  __name__ имя, с которым был определён этот метод  
  im_class объект класса, у которого запрашивается этот метод (1)
  im_func или __func__ объект функции, содержащий реализацию метода  
  im_self or __self__ экземлпяр, к которому привязан метод, или None  
function __doc__ строка документации  
  __name__ имя, с которым эта функция была определена  
  func_code объект кода, содержащий скомпилированный bytecode функции  
  func_defaults кортеж значений по умолчанию для аргументов  
  func_doc (то же, что и __doc__)  
  func_globals глобальное пространство имён, в котором была определена функция  
  func_name (то же, что и __name__)  
generator __iter__ определена для поддержки итерации через контейнер  
  close вызывает исключение GeneratorExit внутри генератора, чтобы прекратить итерацию  
  gi_code объект кода  
  gi_frame объект фрейма или, возможно, None, если генератор был исчерпан  
  gi_running равен 1, если генератор исчерпан, иначе 0  
  next возвращает следующий элемент из контейнера  
  send возобновляет генератор и “посылает” значение, которое становится результатом текущего выражения yield  
  throw используется для возбуждения исключения внутри генератора  
traceback tb_frame объект фрейма на этом уровне  
  tb_lasti индекс последней применённой инструкции в байткоде  
  tb_lineno номер текущей строки в исходном коде Python  
  tb_next следующий внутренний объект трассировки (вызываемый на этом уровне)  
frame f_back следующий внешний объект фрейма (вызывающий этот фрейм)  
  f_builtins встроенное пространство имён, видимое этим фреймом.  
  f_code объект кода, выполняемый в этом фрейме  
  f_exc_traceback трассировка, если есть в этом фрейме, иначе None  
  f_exc_type f_exc_type тип исключения, если возникает в этом фрейме, иначе None  
  f_exc_value значение исключения, если возникает в этом фрейме, иначе None  
  f_globals f_globals глобальное пространство имён, видимое этим фреймом  
  f_lasti f_lasti индекс последней выполненной инструкции в байткоде  
  f_lineno номер текущей строки в исходном коде Python  
  f_locals f_locals локальное пространство имён, видимое в этом фрейме  
  f_restricted 0 или 1, если фрейм находится в ограниченном режиме выполнения  
  f_trace трассировочная функци для этого фрейма, или None  
code co_argcount число аргументов (не включая аргументы * или **)  
  co_code строка, или сырой скомпилированный байт-код  
  co_consts co_consts кортеж констант, используемых в байт-коде  
  co_filename имя файла, в котором этот объект кода был создан  
  co_firstlineno номер первой строки в исходном коде Python  
  co_flags bitmap: 1=optimized | 2=newlocals | 4=*arg | 8=**arg  
  co_lnotab кодированое отображение номер стр+оки на индекс байт-кода  
  co_name имя, с которым этот объект кода был определён  
  co_names кортеж имён локальных переменных  
  co_nlocals co_nlocals количество локальных переменных  
  co_stacksize требуемый стек для виртуальной машины  
  co_varnames кортеж имён аргументов и локальных переменных  
builtin __doc__ строка документации  
  __name__ оригинальне имя этой функции или метода  
  __self__ экземпляр, к которому привязан этот метод, или None  

Note:

  1. Changed in version 2.2: im_class используется для ссылки на класс, который определяет этот метод

inspect.getmembers(object[, predicate])[source]

Возвращает все члены объекта в списке, состоящем из пар вида (name, value), отсортированных по имени. Если передан не обязательный аргумент predicate, то будут включены только те члены, для которых predicate возвращает True.

Note

getmembers() не возвращает атрибуты метакласса, если аргумент является классом (это поведение унаследовано из функции dir()).

inspect.getmoduleinfo(path)[source]

Возвращает кортеж значений, который описывает как Python будет интерпретировать файл, определяемый path*`ом, если это модуль, или ``None``, если он не может быть идентифицирован как модуль. Возвращаемый кортеж имеет вид ``(name, suffix, mode, module_type)``, где *name - имя модуля без имён окружающих его пакетов, suffix - оставшаяся часть имени файла (может не быть расширением с точкой), mode - режим для функции open(), который будет использоваться ('r' или 'rb') и module_type - число, определяющее тип модуля. module_type будет иметь значение, которое можно сравнить с константами, определёнными в модуле imp, более подробную информацию можно найти в документации к тому модулю.

Changed in version 2.6: Возвращает named tuple ModuleInfo(name, suffix, mode, module_type).

inspect.getmodulename(path)[source]

Возвращает имя модуля, определённого путём path, без окружающих его пакетов. Используется тот же самый алгоритм, который использует интерпретатор при поиске модулей. Если по этому имени по правилам интерпретатора невозможно найти модуль будет возвращено None.

inspect.ismodule(object)[source]

Возвращает true, если объект является модулем.

inspect.isclass(object)[source]

Возвращает true, если объект является классом, не важно, встроенным или пользовательским.

inspect.ismethod(object)[source]

Возвращает true, если обект является связанным методом, написанным на Python.

inspect.isfunction(object)[source]

Возвращает true, если объект является функцией Python, сюда же относятся функции, созданные при помощи выражения lambda.

Note

Примечание переводчика: встроенные функции возвращают false:

>>> inspect.isfunction(len)
False
>>> len
<built-in function len>
inspect.isgeneratorfunction(object)[source]

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

New in version 2.6.

inspect.isgenerator(object)[source]

Возвращает true, если объект является генератором.

New in version 2.6.

inspect.istraceback(object)[source]

Возвращает true, если объект является трассировкой.

inspect.isframe(object)[source]

Возвращает true, если объект является фреймом.

inspect.iscode(object)[source]

Возвращает true, если объект является кодом.

inspect.isbuiltin(object)[source]

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

inspect.isroutine(object)[source]

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

inspect.isabstract(object)[source]

Возвращает true, если объект является абстрактным базовым классом.

New in version 2.6.

inspect.ismethoddescriptor(object)[source]

Возвращает true, если объект является дескриптором метода, но ismethod(), isclass(), isfunction() или isbuiltin() не возвращают true.

Это новая возможность, начиная с Python 2.2, и, например, возвращает true для int.__add__. Объект, проходящий этот тест, имет атрибут __get__, но не имеет атрибута __set__, во всем остальном атрибуты могут отличаться. Обычно имеют смысл __name__ и __doc__.

Методы, реализованные при помощи дескрипторов, которые проходят какой-либо другой тест, возвращают false для теста ismethoddescriptor() просто потому, что другие тесты предоставляют больше информации, например, если объект прошёл тест ismethod(), то Вы можете быть уверены, что у него есть атрибут im_func.

inspect.isdatadescriptor(object)[source]

Возвращает true, если объект является дескриптором данных.

Декскриптор данных имеет оба атрибута: __get__ и __set__. Примерами являются свойства (определённые в Python), getset`ы, и member`ы. Последние два определены в C и для них есть более конкретные тесты, реализованные в Python. Обычно дескрипторы данных так же имеют атрибуты __name__ и __doc__ (свойства, getset`ы, и member`ы имет оба этих атрибута), но это не обязательно.

New in version 2.3.

inspect.isgetsetdescriptor(object)[source]

Return true if the object is a getset descriptor.

New in version 2.5.

inspect.ismemberdescriptor(object)[source]

Возвращает true, если объект является дескриптором member`а.

New in version 2.5.

Получение исходного кода

inspect.getdoc(object)[source]

Получить строку документации для объекта, обработанную функцией cleandoc().

inspect.getcomments(object)[source]

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

inspect.getfile(object)[source]

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

inspect.getmodule(object)[source]

Пытается угадать, в каком модуле был определён объект.

inspect.getsourcefile(object)[source]

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

inspect.getsourcelines(object)[source]

Возвращает кортеж, первый элемент которого - список строк исходного кода, а второй - номер первой строки кода, в которой был определён объект. Аргументом может быть модуль, класс, метод, функция, трассировка, фрейм или объект кода. Вызывается IOError, если исходный код не может быть получен.

Note

Вызовет TypeError, если объект является встроенным модулем, классом или функцией:

>>> inspect.getsourcelines(D)
Traceback (most recent call last):
  File "<pyshell#388>", line 1, in <module>
    inspect.getsourcelines(D)
  File "C:\Python27\lib\inspect.py", line 690, in getsourcelines
    lines, lnum = findsource(object)
  File "C:\Python27\lib\inspect.py", line 526, in findsource
    file = getfile(object)
  File "C:\Python27\lib\inspect.py", line 408, in getfile
    raise TypeError('{!r} is a built-in class'.format(object))
TypeError: <module '__main__' (built-in)> is a built-in class
inspect.getsource(object)[source]

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

inspect.cleandoc(doc)[source]

Убирает отступы из строк документации, чтобы выровнять с блоком кода. Все пробелы, которые можно равным образом удалить начиная со второй строки, удаляются. Кроме того, все знаки табуляции заменяются на пробелы.

New in version 2.6.

Классы и функции

inspect.getclasstree(classes[, unique])[source]

Преобразует переданный список классов в иерархию вложенных списокв. Каждый вложенный список содержит классы, унаследованные от класса, находящегося в списке более высокого уровня. Каждый элемент является 2-х элементным кортежем, содержащим класс и кортеж его базовых классов. Если аргумент unique = True, то каждый класс появляется в списке только один раз. Иначе, классы, использующие множественное наследование и их потомки будут появляться несколько раз.

inspect.getargspec(func)[source]

Получает имена и значения по умолчанию для аргументов функции Python. Возвращается кортеж из четырёх элемнтов: (args, varargs, keywords, defaults). args - список имён аргументов (может содержать вложенные списки). varargs и keywords - имена аргументов * и ** или None. defaults - кортеж значений аргументов по умолчанию или None если их нет; Если этот кортеж имеет n элементов, то они соответствуют последним n элементам, перечисленным в args.

Changed in version 2.6: Возвращает named tuple ArgSpec(args, varargs, keywords, defaults).

inspect.getargvalues(frame)[source]

Получает информацию об аргументах, переданных в конкретный фрейм. Возвращается кортеж из четырёх элементов: (args, varargs, keywords, locals). args - список имён аргументов (может содержать вложенные списки). varargs и keywords - имена аргументов * и ** или None. locals - локальный словарь данного фрейма.

Changed in version 2.6: Возвращает named tuple ArgInfo(args, varargs, keywords, locals).

inspect.formatargspec(args[, varargs, varkw, defaults, formatarg, formatvarargs, formatvarkw, formatvalue, join])[source]

Форматирует возвращаемое значение функции getargspec(). Аргументы format* соответсвуют опциональным функциям, которые вызываются для преобразования имён и значений в строки.

inspect.formatargvalues(args[, varargs, varkw, locals, formatarg, formatvarargs, formatvarkw, formatvalue, join])[source]

Форматирует возвращаемое значение функции getargvalues(). Аргументы format* соответсвуют опциональным функциям, которые вызываются для преобразования имён и значений в строки.

inspect.getmro(cls)[source]

Возвращает кортеж базовых классов для класса cls, включая его самого, в порядке, используемом для разрешения (поиска) методов. Каждый класс в этом кортеже присутствует только один раз. Обратите внимание, что порядок разрешения методов зависит от типа класса. Если не используется какой-то очень своеобразный пользовательский метатип, то cls будет первым элементом кортежа.

inspect.getcallargs(func[, *args][, **kwds])[source]

Связывает args и kwds с именами аргументов функции или метода func, как если бы эта функция или метод были вызваны с этими аргументами. Для связанных методов связывает так же первый аргумент (обычно с именем self) с ассоциированным экземпляром. Возвращается словарь, который отображает имена аргументов (включая имена аргументов * и **, если они есть) на их значения из args и kwds. В случае некорректного вызова func, то есть в случае, когда func(*args, **kwds) вызвало бы исключение из-за не совпадающей сигнатуры, вызывается то же самое исключение с похожим или тем же сообщением. Например:

>>> from inspect import getcallargs
>>> def f(a, b=1, *pos, **named):
...     pass
>>> getcallargs(f, 1, 2, 3)
{'a': 1, 'named': {}, 'b': 2, 'pos': (3,)}
>>> getcallargs(f, a=2, x=4)
{'a': 2, 'named': {'x': 4}, 'b': 1, 'pos': ()}
>>> getcallargs(f)
Traceback (most recent call last):
...
TypeError: f() takes at least 1 argument (0 given)
>>> inspect.getcallargs(f,*(1,2,3,4,5,6),**{'a':'a','b':'b'})
Traceback (most recent call last):
...
TypeError: f() got multiple values for keyword argument 'a'

New in version 2.7.

Стек интерпретатора

Когда следующие функции возвращают “frame records (запись фрейма)”, каждая запись является кортежем из шести элементов: объекта фрейма, имени файла, номера текущей строки, имени функции, списка строк контекста из исходного кода, и индекс текущей строки в этом списке.

Note

Хранение ссылок на объекты фрейма, которые являются первым элементом записи фрейма, возвращаемой этими функциями, может привести к созданию циклических ссылок. Если циклическая ссылка была создана, то жизнь всех объектов, дотупных из объекта, который создал цикл, становится гораздо дольше, даже если активирован детектор циклов Python`a. Если такой цикл должен быть создан, но очень важно убедиться, что он будет принудительно разорван, чтобы избежать отложенного разрушения объектов и возросшего потребления памяти.

Хотя детектор циклов будет отлавливать их, разрушение этих фреймов (и локальных переменных) может быть сделано явно, удалив цикл в выражении finally. Это важно и в том случае, когда детектор циклов был отключён при компиляции или при помощи gc.disable(). Например:

def handle_stackframe_without_leak():
    frame = inspect.currentframe()
    try:
        # делаем что-то с фреймом
    finally:
        del frame

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

inspect.getframeinfo(frame[, context])[source]

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

Changed in version 2.6: Возвращает a named tuple Traceback(filename, lineno, function, code_context, index).

inspect.getouterframes(frame[, context])[source]

Получает список записей фрейма для фрейма и всех внешних фреймов. Эти фреймы представляют вызовы, которые привели к созданию frame. Первый элемент в возвращаемом списке представляет frame; последний - самый внешний вызов стека frame‘а.

inspect.getinnerframes(traceback[, context])[source]

Получает список записей фрейма для фрейма трассировки и всех внутренних фреймов. Эти фреймы последовательно представляют вызовы, сделанные frame*`ом. Первый элемент в возвращаемом списке представляет *traceback; последний - тот фрейм, где было вызвано исключение.

inspect.currentframe()[source]

Возвращает объект фрейма для вызвавшего стека фрейма.

inspect.stack([context])[source]

Возвращает список записей фрейма для стека, в котором произошёл вызов. Первый элемент списка - вызывающий фрейм, последний - самый внешний вызов в стеке.

inspect.trace([context])[source]

Возвращает список записей фрема между текущим фреймом и фреймом, в котором было вызвано перехваченное исключение. Первый элемент списка - вызвавший фрейм, последний - тот, где было вызвано исключение.