inspect — Просмотр живых объектов

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

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

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

1. Типы и члены

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

inspect.getmembers(object[, predicate])

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

Примечание

getmembers() вернёт только атрибуты класса, определенные в метаклассе, когда аргумент — класс, и эти атрибуты были перечислены в пользовательском __dir__() метакласса.

inspect.getmoduleinfo(path)

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

Устаревшая с версии 3.3: Вы можете проверить расширение пути файла по отношению к поддерживаемым расширениям, перечисленным в importlib.machinery, чтобы получить ту же информацию.

inspect.getmodulename(path)

Возвращает имя модуля по имени файла path без включения имен содержащих пакетов. Проверяется расширение файла по отношению ко всем записям в importlib.machinery.all_suffixes(). Если он совпадает, возвращается конечный компонент пути с удаленным расширением. В противном случае, возвращается None.

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

Изменено в версии 3.3: Эта функция теперь основана непосредственно на importlib, а не на устаревшей getmoduleinfo().

inspect.ismodule(object)

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

inspect.isclass(object)

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

inspect.ismethod(object)

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

inspect.isfunction(object)

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

inspect.isgeneratorfunction(object)

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

inspect.isgenerator(object)

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

inspect.iscoroutinefunction(object)

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

Введено в версии 3.5.

inspect.iscoroutine(object)

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

Введено в версии 3.5.

inspect.isawaitable(object)

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

Также может быть использован для различения корутин, основанных на генераторах, от обычных генераторов:

def gen():
    yield
@types.coroutine
def gen_coro():
    yield

assert not isawaitable(gen())
assert isawaitable(gen_coro())

Введено в версии 3.5.

inspect.istraceback(object)

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

inspect.isframe(object)

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

inspect.iscode(object)

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

inspect.isbuiltin(object)

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

inspect.isroutine(object)

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

inspect.isabstract(object)

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

inspect.ismethoddescriptor(object)

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

Например, это верно для int.__add__. Объект, проходящий этот тест, имеет метод __get__(), но не метод __set__(), но набор атрибутов варьируется. Атрибут __name__ обычно имеет смысл, и __doc__ часто тоже.

Методы, реализованные через описатели, которые также проходят один из других тестов, возвращают False от теста ismethoddescriptor(), просто потому что другие тесты обещают больше – вы можете, например, полагаться на наличие атрибута __func__ (и т. д.) когда объект проходит тест ismethod().

inspect.isdatadescriptor(object)

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

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

inspect.isgetsetdescriptor(object)

Возвращает True, если объект является описателем getset.

Деталь реализации CPython: getset являются атрибутами, определёнными в расширяемых модулях через структуры PyGetSetDef. В реализациях Python без таких типов этот метод всегда возвращает False.

inspect.ismemberdescriptor(object)

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

Деталь реализации CPython: Описатели членов являются атрибутами, определёнными в расширяемых модулях через структуры PyMemberDef. В реализациях Python без таких типов этот метод всегда возвращает False.

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

inspect.getdoc(object)

Получить строку документации для объекта, очищенную с помощью cleandoc(). Если строка документации для объекта не предоставлена, а объект является классом, методом, свойством или описателем, получить строку документации из иерархии наследования.

Изменено в версии 3.5: Строки документации теперь наследуются, если не переопределены.

inspect.getcomments(object)

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

inspect.getfile(object)

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

inspect.getmodule(object)

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

inspect.getsourcefile(object)

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

inspect.getsourcelines(object)

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

Изменено в версии 3.3: Возникает ошибка OSError вместо IOError, которая теперь является псевдонимом первой.

inspect.getsource(object)

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

Изменено в версии 3.3: Возникает ошибка OSError вместо IOError, которая теперь является псевдонимом первой.

inspect.cleandoc(doc)

Очищает отступы из строк документации, которые отступы для выравнивания с блоками кода.

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

3. Инспектирование вызываемых объектов с помощью объекта Signature

Объект Signature представляет сигнатуру вызова объекта вызываемого объекта и его аннотацию возврата. Чтобы получить объект Signature, используйте функцию signature().

inspect.signature(callable, *, follow_wrapped=True)

Возвращает объект Signature для данного callable:

>>> from inspect import signature
>>> def foo(a, *, b:int, **kwargs):
...     pass

>>> sig = signature(foo)

>>> str(sig)
'(a, *, b:int, **kwargs)'

>>> str(sig.parameters['b'])
'b:int'

>>> sig.parameters['b'].annotation
<class 'int'>

Принимает широкий спектр вызываемых объектов Python, от обычных функций и классов до объектов functools.partial().

Возвращает ValueError, если сигнатура не может быть предоставлена, и TypeError, если этот тип объекта не поддерживается.

Новая версия с 3.5: follow_wrapped параметр. Передайте False для получения сигнатуры callable конкретно (callable.__wrapped__ не будет использоваться для разворачивания декорированных вызываемых объектов.)

Примечание

Некоторые вызываемые объекты могут не быть инспектируемыми в некоторых реализациях Python. Например, в CPython некоторые встроенные функции, определённые на C, не предоставляют метаданных о своих аргументах.

class inspect.Signature(parameters=None, *, return_annotation=Signature.empty)

Объект Signature представляет сигнатуру вызова функции и её аннотацию возврата. Для каждого параметра, принимаемого функцией, он хранит объект Parameter в своем наборе parameters.

Необязательный аргумент parameters — последовательность объектов Parameter, которая проверяется на наличие параметров с дублирующимися именами и на правильность порядка параметров: сначала позиционные-только, затем позиционные-или-именованные, и параметры по умолчанию следуют за параметрами без значений по умолчанию.

Необязательный аргумент return_annotation, который может быть произвольным объектом Python, представляет аннотацию «возврат» вызываемого объекта.

Объекты Signature являются неизменяемыми. Используйте Signature.replace() для создания изменённой копии.

Изменено в версии 3.5: Объекты Signature могут быть сериализованы и хэшированы.

empty

Специальный маркер уровня класса для указания отсутствия аннотации возврата.

parameters

Упорядоченное отображение имён параметров к соответствующим объектам Parameter.

return_annotation

Аннотация «возврат» для вызываемого объекта. Если у вызываемого объекта нет аннотации «возврат», этот атрибут устанавливается в Signature.empty.

bind(*args, **kwargs)

Создаёт отображение из позиционных и именованных аргументов в параметры. Возвращает BoundArguments, если *args и **kwargs соответствуют сигнатуре, или генерирует TypeError.

bind_partial(*args, **kwargs)

Работает так же, как Signature.bind(), но позволяет опустить некоторые обязательные аргументы (эмулирует поведение functools.partial()). Возвращает BoundArguments или генерирует TypeError, если переданные аргументы не соответствуют сигнатуре.

replace(*[, parameters][, return_annotation])

Создаёт новый экземпляр Signature, основанный на экземпляре, для которого был вызван метод replace. Можно передать другие parameters и/или return_annotation для переопределения соответствующих свойств исходной сигнатуры. Для удаления аннотации возврата из скопированной сигнатуры передайте Signature.empty.

>>> def test(a, b):
...     pass
>>> sig = signature(test)
>>> new_sig = sig.replace(return_annotation="new return anno")
>>> str(new_sig)
"(a, b) -> 'new return anno'"

classmethod from_callable(obj, *, follow_wrapped=True)

Возвращает объект Signature (или его подкласс) для заданного вызываемого объекта obj. Передайте follow_wrapped=False для получения сигнатуры obj без разворачивания его __wrapped__ цепочки.

Этот метод упрощает наследование от Signature:

class MySignature(Signature):
    pass
sig = MySignature.from_callable(min)
assert isinstance(sig, MySignature)

Новая версия с 3.5.

class inspect.Parameter(name, kind, *, default=Parameter.empty, annotation=Parameter.empty)

Объекты Parameter являются неизменяемыми. Вместо изменения объекта Parameter, используйте Parameter.replace() для создания изменённой копии.

Изменено в версии 3.5: Объекты Parameter могут быть сериализованы и хэшированы.

empty

Специальный маркер уровня класса для указания отсутствия значений по умолчанию и аннотаций.

name

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

default

Значение по умолчанию для параметра. Если у параметра нет значения по умолчанию, этот атрибут устанавливается в Parameter.empty.

annotation

Аннотация для параметра. Если у параметра нет аннотации, этот атрибут устанавливается в Parameter.empty.

kind

Описывает способ привязки значений аргументов к параметру. Возможные значения (доступные через Parameter, например, Parameter.KEYWORD_ONLY):

Имя	Значение
POSITIONAL_ONLY	Значение должно быть передано как позиционный аргумент. В Python нет явного синтаксиса для определения позиционных-только параметров, но многие встроенные и функции расширяемых модулей (особенно те, которые принимают только один или два параметра) принимают их.
POSITIONAL_OR_KEYWORD	Значение может быть передано как именованный или позиционный аргумент (это стандартное поведение привязки для функций, реализованных на Python.)
VAR_POSITIONAL	Кортеж позиционных аргументов, которые не привязаны к другим параметрам. Соответствует параметру *args в определении функции Python.
KEYWORD_ONLY	Значение должно быть передано как именованный аргумент. Параметры только с именованием — это те, которые появляются после записи * или *args в определении функции Python.
VAR_KEYWORD	Словарь именованных аргументов, которые не привязаны к другим параметрам. Соответствует параметру **kwargs в определении функции Python.

Пример: распечатать все именованные-только аргументы без значений по умолчанию:

>>> def foo(a, b, *, c, d=10):
...     pass

>>> sig = signature(foo)
>>> for param in sig.parameters.values():
...     if (param.kind == param.KEYWORD_ONLY and
...                        param.default is param.empty):
...         print('Parameter:', param)
Parameter: c

replace(*[, name][, kind][, default][, annotation])

Создаёт новый экземпляр Parameter, основанный на экземпляре, для которого был вызван метод replace. Чтобы переопределить атрибут Parameter, передайте соответствующий аргумент. Чтобы удалить значение по умолчанию и/или аннотацию из Parameter, передайте Parameter.empty.

>>> from inspect import Parameter
>>> param = Parameter('foo', Parameter.KEYWORD_ONLY, default=42)
>>> str(param)
'foo=42'

>>> str(param.replace()) # Will create a shallow copy of 'param'
'foo=42'

>>> str(param.replace(default=Parameter.empty, annotation='spam'))
"foo:'spam'"

Изменено в версии 3.4: В Python 3.3 объектам Parameter разрешалось устанавливать name в None если их kind было установлено в POSITIONAL_ONLY. Это больше не разрешено.

class inspect.BoundArguments

Результат вызова Signature.bind() или Signature.bind_partial(). Содержит сопоставление аргументов параметрам функции.

arguments

Упорядоченное, изменяемое отображение (collections.OrderedDict) имён параметров к значениям аргументов. Содержит только явно привязанные аргументы. Изменения в arguments будут отражены в args и kwargs.

Должен использоваться совместно с Signature.parameters для обработки аргументов.

Примечание

Аргументы, для которых Signature.bind() или Signature.bind_partial() использовали значение по умолчанию, пропускаются. Однако при необходимости используйте BoundArguments.apply_defaults(), чтобы добавить их.

args

Кортеж значений позиционных аргументов. Динамически вычисляется из атрибута arguments.

kwargs

Словарь значений именованных аргументов. Динамически вычисляется из атрибута arguments.

signature

Ссылка на родительский объект Signature.

apply_defaults()

Устанавливает значения по умолчанию для отсутствующих аргументов.

Для аргументов с переменной позиционной частью (*args) значение по умолчанию — пустой кортеж.

Для аргументов с переменной именованной частью (**kwargs) значение по умолчанию — пустой словарь.

>>> def foo(a, b='ham', *args): pass
>>> ba = inspect.signature(foo).bind('spam')
>>> ba.apply_defaults()
>>> ba.arguments
OrderedDict([('a', 'spam'), ('b', 'ham'), ('args', ())])

Введено в версии 3.5.

Свойства args и kwargs могут использоваться для вызова функций:

def test(a, *, b):
    ...

sig = signature(test)
ba = sig.bind(10, b=20)
test(*ba.args, **ba.kwargs)

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

inspect.getclasstree(classes, unique=False)

Выстраивает заданный список классов в иерархию вложенных списков. Вложенные списки содержат классы, производные от класса, запись которого непосредственно предшествует списку. Каждая запись — это кортеж из 2 элементов: класс и кортеж его базовых классов. Если аргумент unique имеет значение true, в возвращаемой структуре для каждого класса из заданного списка появляется ровно одна запись. В противном случае классы с множественной наследованием и их потомки будут появляться несколько раз.

inspect.getargspec(func)

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

Устарело начиная с версии 3.0: Используйте signature() и Объект сигнатуры, которые предоставляют более удобный API для интроспекции вызываемых объектов.

inspect.getfullargspec(func)

Возвращает имена и значения по умолчанию аргументов Python-функции. Возвращается именованный кортеж:

FullArgSpec(args, varargs, varkw, defaults, kwonlyargs, kwonlydefaults, annotations)

args — список имён аргументов. varargs и varkw — имена * и ** аргументов или None. defaults — кортеж из n значений по умолчанию для последних n аргументов, или None если аргументов по умолчанию нет. kwonlyargs — список имён только-именованных аргументов. kwonlydefaults — словарь, сопоставляющий имена из kwonlyargs с их значениями по умолчанию. annotations — словарь, сопоставляющий имена аргументов с их аннотациями.

Первые четыре элемента кортежа соответствуют getargspec().

Изменено в версии 3.4: Эта функция теперь основана на signature(), но по-прежнему игнорирует __wrapped__ атрибуты и включает уже привязанный первый параметр в выходные данные сигнатуры для связанных методов.

Устарело начиная с версии 3.5: Используйте signature() и Объект сигнатуры, которые предоставляют более удобный API для интроспекции вызываемых объектов.

inspect.getargvalues(frame)

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

Примечание

Эта функция по ошибке была помечена как устаревшая в Python 3.5.

inspect.formatargspec(args[, varargs, varkw, defaults, kwonlyargs, kwonlydefaults, annotations[, formatarg, formatvarargs, formatvarkw, formatvalue, formatreturns, formatannotations]])

Форматирует описание аргументов из значений, возвращаемых getargspec() или getfullargspec().

Первые семь аргументов — (args, varargs, varkw, defaults, kwonlyargs, kwonlydefaults, annotations).

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

Например:

>>> from inspect import formatargspec, getfullargspec
>>> def f(a: int, b: float):
...     pass
...
>>> formatargspec(*getfullargspec(f))
'(a: int, b: float)'

Устарело начиная с версии 3.5: Используйте signature() и Объект сигнатуры, которые предоставляют более удобный API для интроспекции вызываемых объектов.

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

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

Примечание

Эта функция по ошибке была помечена как устаревшая в Python 3.5.

inspect.getmro(cls)

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

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

Связывает args и kwds с именами аргументов Python-функции или метода 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,)}
True
>>> getcallargs(f, a=2, x=4) == {'a': 2, 'named': {'x': 4}, 'b': 1, 'pos': ()}
True
>>> getcallargs(f)
Traceback (most recent call last):
...
TypeError: f() missing 1 required positional argument: 'a'

Добавлен в версии 3.2.

Устарел начиная с версии 3.5: Используйте Signature.bind() и Signature.bind_partial() вместо этого.

inspect.getclosurevars(func)

Получить отображение ссылок на внешние имена в Python-функции или методе func на их текущие значения. Возвращается кортеж с именами ClosureVars(nonlocals, globals, builtins, unbound). nonlocals сопоставляет имена с лексическими переменными замыкания, globals — с глобальными переменными модуля функции, а builtins — с встроенными переменными, видимыми из тела функции. unbound — это множество имен, используемых в функции, которые не могли быть разрешены с учётом текущих глобальных переменных модуля и встроенных переменных.

TypeError возникает, если func не является Python-функцией или методом.

Добавлен в версии 3.3.

inspect.unwrap(func, *, stop=None)

Получить объект, обернутый func. Он следует цепочке атрибутов __wrapped__, возвращая последний объект в цепочке.

stop — это необязательная функция обратного вызова, принимающая объект в цепочке обёртки в качестве единственного аргумента, которая позволяет прервать процесс распаковки, если функция обратного вызова возвращает значение истинности. Если функция обратного вызова никогда не возвращает значение истинности, возвращается последний объект в цепочке, как обычно. Например, signature() использует это, чтобы остановить распаковку, если у любого объекта в цепочке определён атрибут __signature__.

ValueError возникает, если встречена циклическая ссылка.

Добавлен в версии 3.4.

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

При возврате «записей фрейма» этими функциями каждая запись представляет собой кортеж с именами FrameInfo(frame, filename, lineno, function, code_context, index). Кортеж содержит объект фрейма, имя файла, номер строки текущей строки, имя функции, список строк контекста из исходного кода и индекс текущей строки в этом списке.

def handle_stackframe_without_leak():
    frame = inspect.currentframe()
    try:
        # do something with the frame
    finally:
        del frame

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

inspect.getframeinfo(frame, context=1)

Получить информацию об объекте фрейма или трассировки. Возвращается кортеж с именами Traceback(filename, lineno, function, code_context, index).

inspect.getouterframes(frame, context=1)

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

Изменено в версии 3.5: Возвращается список кортежей с именами FrameInfo(frame, filename, lineno, function, code_context, index).

inspect.getinnerframes(traceback, context=1)

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

Изменено в версии 3.5: Возвращается список кортежей с именами FrameInfo(frame, filename, lineno, function, code_context, index).

inspect.currentframe()

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

Деталь реализации CPython: Эта функция полагается на поддержку фреймов стека Python в интерпретаторе, которая не гарантируется во всех реализациях Python. Если выполняется в реализации без поддержки фреймов стека Python, эта функция возвращает None.

inspect.stack(context=1)

Возвращает список записей фрейма для стека вызывающей функции. Первый элемент возвращаемого списка представляет вызывающую функцию; последний элемент представляет самый внешний вызов в стеке.

Изменено в версии 3.5: Возвращается список кортежей с именами FrameInfo(frame, filename, lineno, function, code_context, index).

inspect.trace(context=1)

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

Изменено в версии 3.5: Возвращается список кортежей с именами FrameInfo(frame, filename, lineno, function, code_context, index).

6. Статическое извлечение атрибутов

Как getattr(), так и hasattr() могут инициировать выполнение кода при извлечении или проверке существования атрибутов. Дескрипторы, такие как свойства, будут вызваны, и __getattr__() и __getattribute__() могут быть вызваны.

В случаях, когда требуется пассивная интроспекция, например, для инструментов документирования, это может быть неудобно. getattr_static() имеет такую же сигнатуру, как getattr(), но избегает выполнения кода при извлечении атрибутов.

inspect.getattr_static(obj, attr, default=None)

Извлечь атрибуты, не вызывая динамического поиска через протокол дескрипторов, __getattr__() или __getattribute__().

Примечание: эта функция может не получить все атрибуты, которые может получить getattr (например, динамически созданные атрибуты), и может найти атрибуты, которые getattr не может (например, дескрипторы, вызывающие AttributeError). Она также может возвращать объекты-дескрипторы вместо членов экземпляра.

Если __dict__ экземпляра затенён другим членом (например, свойством), эта функция не сможет найти члены экземпляра.

Добавлен в версии 3.2.

getattr_static() не разрешает дескрипторы, например, слотовые дескрипторы или дескрипторы getset на объектах, реализованных на C. Вместо подчинённого атрибута возвращается объект-дескриптор.

Вы можете обработать их с помощью следующего кода. Обратите внимание, что при произвольном использовании дескрипторов getset вызов этих методов может привести к выполнению кода:

# example code for resolving the builtin descriptor types
class _foo:
    __slots__ = ['foo']

slot_descriptor = type(_foo.foo)
getset_descriptor = type(type(open(__file__)).name)
wrapper_descriptor = type(str.__dict__['__add__'])
descriptor_types = (slot_descriptor, getset_descriptor, wrapper_descriptor)

result = getattr_static(some_object, 'foo')
if type(result) in descriptor_types:
    try:
        result = result.__get__()
    except AttributeError:
        # descriptors can raise AttributeError to
        # indicate there is no underlying value
        # in which case the descriptor itself will
        # have to do
        pass

7. Текущее состояние генераторов и корутин

При реализации планировщиков корутин и для других расширенных применений генераторов полезно определить, выполняется ли генератор в данный момент, ожидает ли он начала или возобновления выполнения или уже завершился. getgeneratorstate() позволяет легко определить текущее состояние генератора.

inspect.getgeneratorstate(generator)

Получение текущего состояния генератор-итератора.

Возможные состояния:

• GEN_CREATED: Ожидание начала выполнения.
• GEN_RUNNING: В данный момент выполняется интерпретатором.
• GEN_SUSPENDED: В данный момент приостановлен на выражении yield.
• GEN_CLOSED: Выполнение завершено.

Введено в версии 3.2.

inspect.getcoroutinestate(coroutine)

Получение текущего состояния объекта корутины. Функция предназначена для использования с объектами корутин, созданными функциями async def, но примет любой объект, подобный корутине, у которого есть атрибуты cr_running и cr_frame.

Возможные состояния:

• CORO_CREATED: Ожидание начала выполнения.
• CORO_RUNNING: В данный момент выполняется интерпретатором.
• CORO_SUSPENDED: В данный момент приостановлен на выражении await.
• CORO_CLOSED: Выполнение завершено.

Введено в версии 3.5.

Текущее внутреннее состояние генератора также можно запросить. Это в основном полезно для тестирования, чтобы убедиться, что внутреннее состояние обновляется так, как ожидается:

inspect.getgeneratorlocals(generator)

Получение отображения живых локальных переменных в генераторе и их текущих значений. Возвращается словарь, сопоставляющий имена переменных со значениями. Это эквивалентно вызову locals() в теле генератора, и все те же оговорки применимы.

Если генератор — это генератор без текущей связанной фрейма, то возвращается пустой словарь. TypeError генерируется, если генератор не является объектом Python генератора.

Подробности реализации CPython: Эта функция полагается на то, что генератор предоставляет фрейм стека Python для интроспекции, что не гарантируется во всех реализациях Python. В таких случаях эта функция всегда вернёт пустой словарь.

Введено в версии 3.3.

inspect.getcoroutinelocals(coroutine)

Эта функция аналогична getgeneratorlocals(), но работает для объектов корутин, созданных функциями async def.

Введено в версии 3.5.

8. Флаги кода объектов

Объекты кода Python имеют атрибут co_flags, который представляет собой битовую карту следующих флагов:

inspect.CO_OPTIMIZED

Объект кода оптимизирован, используя быстрые локальные переменные.

inspect.CO_NEWLOCALS

Если установлен, для фрейма f_locals будет создан новый словарь при выполнении объекта кода.

inspect.CO_VARARGS

Объект кода имеет переменный позиционный параметр (подобный *args).

inspect.CO_VARKEYWORDS

Объект кода имеет переменный именованный параметр (подобный **kwargs).

inspect.CO_NESTED

Флаг установлен, когда объект кода — это вложенная функция.

inspect.CO_GENERATOR

Флаг установлен, когда объект кода — это функция-генератор, то есть при выполнении объекта кода возвращается объект генератора.

inspect.CO_NOFREE

Флаг установлен, если нет свободных или ячейковых переменных.

inspect.CO_COROUTINE

Флаг установлен, когда объект кода — это функция корутины, то есть при выполнении объекта кода возвращается объект корутины. См. PEP 492 для получения дополнительной информации.

Введено в версии 3.5.

inspect.CO_ITERABLE_COROUTINE

Используется для преобразования генераторов в генераторные корутины. Объекты генераторов с этим флагом могут использоваться в выражении await, и могут yield from объекты корутин. См. PEP 492 для получения дополнительной информации.

Введено в версии 3.5.

9. Командная строка

Модуль inspect также предоставляет базовые возможности интроспекции из командной строки.

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

--details

Вывести информацию о заданном объекте вместо исходного кода