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.

Изменено в версии 3.13: Теперь для функций, обёрнутых в functools.partialmethod(), возвращается True, если обёрнутая функция является функцией-генератором Python.

inspect.isgenerator(object)

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

inspect.iscoroutinefunction(object)

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

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

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

Изменено в версии 3.12: Теперь для синхронных функций, помеченных с помощью markcoroutinefunction(), возвращается True.

Изменено в версии 3.13: Теперь для функций, обёрнутых в functools.partialmethod(), возвращается True, если обёрнутая функция является функцией-сопрограммой.

inspect.markcoroutinefunction(func)

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

Это может быть полезно для синхронных функций, возвращающих сопрограмму, если функция передаётся в API, которому требуется iscoroutinefunction().

По возможности предпочтительно использовать функцию async def. Также допустимо вызвать функцию и проверить возвращаемое значение с помощью iscoroutine().

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

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, если обёрнутая функция является функцией асинхронного генератора.

Изменено в версии 3.13: Теперь для функций, обёрнутых в functools.partialmethod(), возвращается True, если обёрнутая функция является функцией-сопрограммой.

inspect.isasyncgen(object)

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

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

inspect.istraceback(object)

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

inspect.isframe(object)

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

inspect.iscode(object)

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

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__() или __delete__(). Кроме того, набор атрибутов может различаться. Обычно наличие атрибута __name__ целесообразно, а наличие __doc__ встречается часто.

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

Изменено в версии 3.13: Эта функция больше не ошибочно считает дескрипторами методов объекты с __get__() и __delete__(), но без __set__() (такие объекты являются дескрипторами данных, а не дескрипторами методов).

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 представляет сигнатуру вызова функции и её аннотацию возвращаемого значения. Для каждого параметра, принимаемого функцией, он хранит объект Parameter в своей коллекции parameters.

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

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

Объекты Signature неизменяемы. Чтобы создать изменённую копию, используйте Signature.replace() или copy.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'"

Объекты Signature также поддерживаются универсальной функцией copy.replace().

format(*, max_width=None)

Создать строковое представление объекта Signature.

Если задан параметр max_width, метод попытается разместить сигнатуру в строках длиной не более max_width символов. Если сигнатура длиннее max_width, каждый параметр будет выведен на отдельной строке.

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

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() или copy.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'"

Объекты Parameter также поддерживаются универсальной функцией copy.replace().

Изменено в версии 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. Аргументы, которые можно передать позиционно, вместо этого включаются в args.

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

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

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

• AGEN_CREATED: Ожидает начала выполнения.
• AGEN_RUNNING: В данный момент выполняется интерпретатором.
• AGEN_SUSPENDED: В данный момент приостановлен на выражении yield.
• AGEN_CLOSED: Выполнение завершено.

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

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

inspect.getgeneratorlocals(generator)

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

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

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

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

inspect.getcoroutinelocals(coroutine)

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

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

inspect.getasyncgenlocals(agen)

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

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

Битовые флаги объектов кода

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

Флаги буфера

class inspect.BufferFlags

Это enum.IntFlag, представляющий флаги, которые можно передать методу __buffer__() объектов, реализующих буферный протокол.

Значение флагов описано в разделе Типы запросов буфера.

SIMPLE

WRITABLE

FORMAT

ND

STRIDES

C_CONTIGUOUS

F_CONTIGUOUS

ANY_CONTIGUOUS

INDIRECT

CONTIG

CONTIG_RO

STRIDED

STRIDED_RO

RECORDS

RECORDS_RO

FULL

FULL_RO

READ

WRITE

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

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

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

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

--details

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