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])

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

Note

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

inspect.getmoduleinfo(path)

Возвращает кортеж значений, который описывает как 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)

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

inspect.ismodule(object)

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

inspect.isclass(object)

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

inspect.ismethod(object)

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

inspect.isfunction(object)

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

Note

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

>>> inspect.isfunction(len)
False
>>> len
<built-in function len>

inspect.isgeneratorfunction(object)

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

New in version 2.6.

inspect.isgenerator(object)

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

New in version 2.6.

inspect.istraceback(object)

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

inspect.isframe(object)

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

inspect.iscode(object)

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

inspect.isbuiltin(object)

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

inspect.isroutine(object)

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

inspect.isabstract(object)

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

New in version 2.6.

inspect.ismethoddescriptor(object)

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

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

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

inspect.isdatadescriptor(object)

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

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

New in version 2.3.

inspect.isgetsetdescriptor(object)

Return true if the object is a getset descriptor.

New in version 2.5.

inspect.ismemberdescriptor(object)

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

New in version 2.5.

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

inspect.getdoc(object)

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

inspect.getcomments(object)

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

inspect.getfile(object)

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

inspect.getmodule(object)

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

inspect.getsourcefile(object)

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

inspect.getsourcelines(object)

Возвращает кортеж, первый элемент которого - список строк исходного кода, а второй - номер первой строки кода, в которой был определён объект. Аргументом может быть модуль, класс, метод, функция, трассировка, фрейм или объект кода. Вызывается 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)

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

inspect.cleandoc(doc)

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

New in version 2.6.

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

inspect.getclasstree(classes[, unique])

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

inspect.getargspec(func)

Получает имена и значения по умолчанию для аргументов функции 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)

Получает информацию об аргументах, переданных в конкретный фрейм. Возвращается кортеж из четырёх элементов: (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])

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

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

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

inspect.getmro(cls)

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

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

Связывает 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])

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

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

inspect.getouterframes(frame[, context])

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

inspect.getinnerframes(traceback[, context])

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

inspect.currentframe()

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

inspect.stack([context])

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

inspect.trace([context])

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