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

Типы и атрибуты

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

inspect.getmembers(object[, predicate])

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

Примечание

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

inspect.isdatadescriptor(object)

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

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

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

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: Теперь вместо IOError вызывается исключение OSError; первое теперь является псевдонимом второго.

inspect.getsource(object)

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

Изменено в версии 3.3: Теперь вместо IOError вызывается исключение OSError; первое теперь является псевдонимом второго.

inspect.cleandoc(doc)

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

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

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

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

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

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

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

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

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

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

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

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

Примечание

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

Особенность реализации CPython: Если у переданного объекта есть атрибут __signature__, он может быть использован для создания сигнатуры. Точная семантика является особенностью реализации и может изменяться без предварительного уведомления. Актуальную семантику см. в исходном коде.

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

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

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

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

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

Изменено в версии 3.5: Теперь объекты Signature можно сериализовать с помощью pickle и использовать в качестве хешируемых.

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 можно сериализовать с помощью pickle и использовать в качестве хешируемых.

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 на основе экземпляра, для которого был вызван метод 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

Изменяемое сопоставление имён параметров со значениями аргументов. Содержит только явно привязанные аргументы. Изменения в 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 модуля inspect из Python 2.

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

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

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

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

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

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

Возвращает объект, обёрнутый в func. Функция проходит по цепочке атрибутов __wrapped__ и возвращает последний объект в цепочке.

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

Если обнаружен цикл, возникает исключение ValueError.

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

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

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

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

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

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

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

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

• Если eval_str имеет значение true, для значений типа str вызывается eval(). (Обратите внимание, что 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)

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

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

Вывести сведения об указанном объекте вместо исходного кода