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

Типы и члены

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

inspect.getmembers(object[, predicate])

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

Примечание

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

inspect.getmembers_static(object[, predicate])

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

Примечание

getmembers_static() может не иметь возможности извлечь все члены, которые может получить getmembers (например, динамически созданные атрибуты), и может найти члены, которые getmembers не может (например, дескрипторы, которые вызывают AttributeError). В некоторых случаях он также может вернуть объекты дескриптора вместо членов экземпляра.

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

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.

Изменено в версии 3.8: Функции, обернутые в functools.partial(), теперь возвращают True, если обернутая функция является функцией-генератором Python.

inspect.isgenerator(object)

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

inspect.iscoroutinefunction(object)

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

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

Изменено в версии 3.8: Функции, обернутые в functools.partial(), теперь возвращают True, если обернутая функция является функцией-генератором корутин.

inspect.iscoroutine(object)

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

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

inspect.isawaitable(object)

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

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

import types

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.

Изменено в версии 3.8: Функции, обернутые в functools.partial(), теперь возвращают True, если обернутая функция является функцией-генератором асинхронных генераторов.

inspect.isasyncgen(object)

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

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

inspect.istraceback(object)

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

inspect.isframe(object)

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

inspect.iscode(object)

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

inspect.isbuiltin(object)

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

inspect.ismethodwrapper(object)

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

Это экземпляры MethodWrapperType, такие как __str__(), __eq__() и __repr__().

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

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

Дескрипторы данных имеют метод __set__ или метод __delete__. Примеры: свойства (определённые в 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.

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

inspect.getdoc(object)

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

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

inspect.getcomments(object)

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

inspect.getfile(object)

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

inspect.getmodule(object)

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

inspect.getsourcefile(object)

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

inspect.getsourcelines(object)

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

Изменено в версии 3.3: OSError возбуждается вместо IOError, теперь являющегося псевдонимом последнего.

inspect.getsource(object)

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

Изменено в версии 3.3: OSError возбуждается вместо IOError, теперь являющегося псевдонимом последнего.

inspect.cleandoc(doc)

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

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

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

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

inspect.signature(callable, *, follow_wrapped=True, globals=None, locals=None, eval_str=False)

Возвращает объект 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().

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

Для объектов, определённых в модулях с использованием строковых аннотаций (from __future__ import annotations), signature() попытается автоматически разаннотировать аннотации, используя get_annotations(). Параметры globals, locals и eval_str передаются в get_annotations() при разрешении аннотаций; см. документацию для get_annotations() для получения инструкций по использованию этих параметров.

Вызывает исключение ValueError, если сигнатура не может быть предоставлена, и TypeError, если этот тип объекта не поддерживается. Кроме того, если аннотации строковые, а eval_str не ложно, вызов(ы) eval() для разаннотации аннотаций в get_annotations() могут потенциально вызвать любые типы исключений.

Слэш (/) в сигнатуре функции обозначает, что параметры перед ним являются только позиционными. Для получения более подробной информации см. статью в FAQ об аргументах только по позиции.

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

Изменено в версии 3.10: Добавлены параметры globals, locals и eval_str.

Примечание

Некоторые вызываемые объекты могут быть не доступны для интроспекции в некоторых реализациях 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. Параметры появляются в строгом порядке определения, включая ключевые параметры только по имени.

Изменено в версии 3.7: Python гарантировал сохранение порядка объявления параметров только по имени, начиная с версии 3.7, хотя на практике этот порядок всегда сохранялся в Python 3.

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, globals=None, locals=None, eval_str=False)

Возвращает объект Signature (или его подкласс) для данного вызываемого объекта obj.

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

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

Его поведение в остальном идентично поведению signature().

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

Изменено в версии 3.10: Добавлены параметры globals, locals и eval_str.

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

kind.description

Описание перечисления Parameter.kind.

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

Пример: выведите все описания аргументов:

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

>>> sig = signature(foo)
>>> for param in sig.parameters.values():
...     print(param.kind.description)
positional or keyword
positional or keyword
keyword-only
keyword-only

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

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

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

Примечание

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

Изменено в версии 3.9: arguments теперь имеет тип dict. Ранее это был тип collections.OrderedDict.

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
{'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)

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

inspect.getclasstree(classes, unique=False)

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

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 модуля Python 2 inspect.

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

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

Изменено в версии 3.7: Python только явно гарантировал, что сохраняет порядок объявления только ключевых параметров начиная с версии 3.7, хотя на практике этот порядок всегда сохранялся в Python 3.

inspect.getargvalues(frame)

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

Примечание

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

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 — необязательный обратный вызов, принимающий объект в цепочке оберток в качестве единственного аргумента, который позволяет прервать процесс разворачивания досрочно, если обратный вызов возвращает значение True. Если обратный вызов никогда не возвращает значение True, последний объект в цепочке возвращается как обычно. Например, signature() использует это, чтобы прекратить разворачивание, если у любого объекта в цепочке определён атрибут __signature__.

ValueError поднимается, если обнаруживается цикл.

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

inspect.get_annotations(obj, *, globals=None, locals=None, eval_str=False)

Вычислить словарь аннотаций для объекта.

obj может быть вызываемым объектом, классом или модулем. Передача объекта любого другого типа вызывает TypeError.

Возвращает словарь. get_annotations() каждый раз возвращает новый словарь; вызов его дважды на одном и том же объекте вернёт два разных, но эквивалентных словаря.

Эта функция обрабатывает несколько деталей за вас:

• Если eval_str равно true, значения типа str будут распарсены с использованием eval(). Это предназначено для использования с аннотациями в виде строк (from __future__ import annotations).
• Если у obj нет словаря аннотаций, возвращает пустой словарь. (Функции и методы всегда имеют словарь аннотаций; классы, модули и другие типы вызываемых объектов могут не иметь его.)
• Игнорирует унаследованные аннотации в классах. Если у класса нет своего словаря аннотаций, возвращает пустой словарь.
• Все обращения к членам объекта и значениям словаря выполняются с помощью getattr() и dict.get() для безопасности.
• Всегда возвращает только что созданный словарь.

eval_str управляет тем, будут ли значения типа str заменены результатом вызова eval() над этими значениями:

• Если eval_str равно true, eval() вызывается для значений типа str. (Обратите внимание, что get_annotations не перехватывает исключения; если eval() вызывает исключение, стек будет развёрнут за пределами вызова get_annotations.)
• Если eval_str равно false (по умолчанию), значения типа str остаются без изменений.

globals и locals передаются в eval(); см. документацию для eval() для получения дополнительной информации. Если globals или locals равны None, эта функция может заменить это значение контекстно-зависимым значением по умолчанию, в зависимости от type(obj):

• Если obj — модуль, globals устанавливается по умолчанию в obj.__dict__.
• Если obj — класс, globals устанавливается по умолчанию в sys.modules[obj.__module__].__dict__, а locals устанавливается по умолчанию в пространство имён класса obj.
• Если obj — вызываемый объект, globals устанавливается по умолчанию в obj.__globals__, хотя если obj — обернутая функция (с использованием functools.update_wrapper()), она предварительно разаворачивается.

Вызов get_annotations — лучший способ доступа к словарю аннотаций любого объекта. См. Рекомендации по использованию аннотаций для получения дополнительной информации о лучших практиках использования аннотаций.

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

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

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

class inspect.FrameInfo

frame

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

filename

Имя файла, связанное с кодом, выполняемым кадром, которому соответствует эта запись.

lineno

Номер строки текущей строки, связанной с кодом, выполняемым кадром, которому соответствует эта запись.

function

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

code_context

Список строк контекста из исходного кода, выполняемого кадром, которому соответствует эта запись.

index

Индекс текущей строки, выполняемой в списке code_context.

positions

Объект dis.Positions, содержащий начальный номер строки, конечный номер строки, начальный смещение столбца и конечный смещение столбца, связанные с инструкцией, выполняемой кадром, которому соответствует эта запись.

Изменено в версии 3.5: Возвращает именованный кортеж вместо tuple.

Изменено в версии 3.11: FrameInfo теперь является экземпляром класса (обратно совместимым с предыдущим именованным кортежем).

class inspect.Traceback

filename

Имя файла, связанное с кодом, выполняемым кадром, которому соответствует этот стек отслеживания.

lineno

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

function

Имя функции, выполняемой кадром, которому соответствует этот стек отслеживания.

code_context

Список строк контекста из исходного кода, выполняемого кадром, которому соответствует этот стек отслеживания.

index

Индекс текущей строки, выполняемой в списке code_context.

positions

Объект dis.Positions, содержащий начальный номер строки, конечный номер строки, начальный смещение столбца и конечный смещение столбца, связанные с инструкцией, выполняемой кадром, которому соответствует этот стек отслеживания.

Изменено в версии 3.11: Traceback теперь является экземпляром класса (обратно совместимым с предыдущим именованным кортежем).

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

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

inspect.getframeinfo(frame, context=1)

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

Изменено в версии 3.11: Возвращается объект Traceback вместо именованного кортежа.

inspect.getouterframes(frame, context=1)

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

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

Изменено в версии 3.11: Возвращается список объектов FrameInfo.

inspect.getinnerframes(traceback, context=1)

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

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

Изменено в версии 3.11: Возвращается список объектов FrameInfo.

inspect.currentframe()

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

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

inspect.stack(context=1)

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

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

Изменено в версии 3.11: Возвращается список объектов FrameInfo.

inspect.trace(context=1)

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

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

Изменено в версии 3.11: Возвращается список объектов FrameInfo.

Получение атрибутов статически

Как 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

Текущее состояние генераторов и сопроцедур

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

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

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

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

inspect.getcoroutinelocals(coroutine)

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

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

Флаги кодовых объектов

Объекты кода 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_COROUTINE

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

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

inspect.CO_ITERABLE_COROUTINE

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

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

inspect.CO_ASYNC_GENERATOR

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

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

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

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

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

--details

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