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

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

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

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

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

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

inspect.getmembers(object[, predicate])

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

Примечание

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

inspect.getmodulename(path)

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

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

Изменено в версии 3.3: Функция основана непосредственно на importlib.

inspect.ismodule(object)

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

inspect.isclass(object)

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

inspect.ismethod(object)

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

inspect.isfunction(object)

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

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.isasyncgenfunction(object)

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

>>> async def agen():
...     yield 1
...
>>> inspect.isasyncgenfunction(agen)
True

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

inspect.isasyncgen(object)

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

Новая в версии 3.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, если объект является абстрактным базовым классом.

inspect.ismethoddescriptor(object)

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

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

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

inspect.isdatadescriptor(object)

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

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

inspect.isgetsetdescriptor(object)

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

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

inspect.ismemberdescriptor(object)

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

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

29.12.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)

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

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

29.12.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 для переопределения соответствующих свойств исходной сигнатуры. Чтобы удалить return_annotation из скопированной Signature, передайте 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.

Деталь реализации CPython: CPython генерирует неявные имена параметров в формате .0 для кодовых объектов, используемых для реализации генераторов и списков с пониманием.

Изменено в версии 3.6: Эти имена параметров доступны в этом модуле как имена вида implicit0.

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, основанный на экземпляре, на котором был вызван метод. Чтобы переопределить атрибут 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)

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

inspect.getclasstree(classes, unique=False)

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

inspect.getargspec(func)

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

Устарело начиная с версии 3.0: Используйте getfullargspec() для обновлённого API, который обычно является прямым заменой, но также правильно обрабатывает аннотации функций и именованные параметры.

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

inspect.getfullargspec(func)

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

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

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

Обратите внимание, что signature() и Объект Signature предоставляют рекомендуемый API для интроспекции вызываемых объектов и поддерживают дополнительные возможности (например, позиционные-только аргументы), которые иногда встречаются в API модулей расширений. Эта функция сохранена в основном для использования в коде, которому требуется сохранять совместимость с API модуля inspect Python 2.

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

Изменено в версии 3.6: Этот метод ранее был задокументирован как устаревший в пользу signature() в Python 3.5, но это решение было пересмотрено, чтобы восстановить чётко поддерживаемый стандартный интерфейс для кода Python 2/3 из одного источника при переходе от устаревшего API getargspec().

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

Форматировать красивое описание аргументов из значений, возвращаемых 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() и Объект 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.

29.12.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)

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

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

inspect.getinnerframes(traceback, context=1)

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

Изменено в версии 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).

29.12.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

29.12.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.

29.12.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, и могут преобразовываться в объекты генераторов-генераторов. Подробнее см. PEP 492.

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

inspect.CO_ASYNC_GENERATOR

Флаг устанавливается, когда объект кода является асинхронной функцией-генератором. При выполнении объекта кода он возвращает объект асинхронного генератора. Подробнее см. PEP 525.

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

29.12.9. Интерфейс командной строки

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

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

--details

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