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.

Для обобщённых псевдонимов классов, например list[int], эта функция возвращает False.

inspect.ismethod(object)

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

Примечание

Например, рассмотрим следующий класс:

>>> class Greeter:
...     def say_hello(self):
...         print('hello!')

Привязанный метод (также известный как метод экземпляра) создаётся при обращении к say_hello (функции, определённой в пространстве имён Greeter) через экземпляр класса Greeter:

>>> instance = Greeter()

>>> instance.say_hello
<bound method Greeter.say_hello of <__main__.Greeter object ...>>
>>> ismethod(instance.say_hello)
True
>>> isfunction(instance.say_hello)
False

Обращение к say_hello через класс Greeter возвращает саму функцию. Для этой функции ismethod() вернёт False, а isfunction() вернёт True:

>>> Greeter.say_hello
<function Greeter.say_hello at 0x7f7503854a90>
>>> ismethod(Greeter.say_hello)
False
>>> isfunction(Greeter.say_hello)
True

Подробности см. в разделе Методы.

inspect.isfunction(object)

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

Пример приведён в примечании к ismethod().

inspect.ispackage(object)

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

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

inspect.isgeneratorfunction(object)

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

Она также возвращает 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, если объект является объектом кода.

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, если объект является дескриптором метода, но не если истинно isclass(), ismethod() или isfunction().

Например, это верно для int.__add__. У объекта, прошедшего эту проверку, есть метод __get__(), но нет метода __set__() или __delete__(). Кроме того, набор атрибутов различается. Атрибут __name__ обычно полезен, как и __doc__.

Для дескрипторов методов, проходящих также любую из других проверок (isclass(), ismethod() или isfunction()), эта функция возвращает False, поскольку другие проверки гарантируют больше: например, можно рассчитывать на наличие атрибута __func__, если объект прошёл проверку ismethod().

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

inspect.isdatadescriptor(object)

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

Дескрипторы данных всегда имеют метод __set__() и/или метод __delete__(). Кроме того, они могут иметь метод __get__().

Примеры дескрипторов данных: properties, getset-дескрипторы и дескрипторы членов. Обратите внимание, что для двух последних (определённых только в расширениях C) доступны более точные проверки: isgetsetdescriptor() и ismemberdescriptor() соответственно.

Хотя у дескрипторов данных также могут быть атрибуты __name__ и __doc__ (как у свойств, getset-дескрипторов и дескрипторов членов), в общем случае это необязательно.

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

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)

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

inspect.getmodule(object)

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

inspect.getsourcefile(object)

Возвращает имя исходного файла Python, в котором был определён объект, или None, если определить способ получения исходного кода невозможно. Если исходный код невозможно получить, возникает исключение OSError. Если объект является встроенным модулем, классом или функцией, возникает исключение 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, annotation_format=Format.VALUE)

Возвращает объект 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() попытается автоматически преобразовать строковые аннотации в исходный вид с помощью annotationlib.get_annotations(). Параметры globals, locals и eval_str передаются в annotationlib.get_annotations() при разрешении аннотаций; инструкции по использованию этих параметров см. в документации annotationlib.get_annotations(). Для управления форматом возвращаемых аннотаций параметру annotation_format можно передать элемент перечисления annotationlib.Format. Например, используйте annotation_format=annotationlib.Format.STRING, чтобы вернуть аннотации в строковом формате.

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

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

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

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

Изменено в версии 3.14: Добавлен параметр annotation_format.

Примечание

В некоторых реализациях 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() или 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, quote_annotation_strings=True)

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

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

Если quote_annotation_strings имеет значение False, аннотации в сигнатуре, являющиеся строками, отображаются без открывающих и закрывающих кавычек. Это полезно, если сигнатура создана с форматом STRING или использовался from __future__ import annotations.

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

Изменено в версии 3.14: Добавлен параметр unquote_annotations.

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	Значение должно быть передано как именованный аргумент. Параметры, доступные только по имени, — это параметры, указанные в определении функции Python после записи * или *args.
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: Ранее этот метод был объявлен устаревшим в пользу signature() в Python 3.5, однако это решение было отменено, чтобы восстановить интерфейс со стандартной и явно поддерживаемой функциональностью для кода 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, format=annotationlib.Format.VALUE)

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

Это псевдоним для annotationlib.get_annotations(); дополнительную информацию см. в документации этой функции.

Внимание

Эта функция может выполнять произвольный код, содержащийся в аннотациях. Дополнительную информацию см. в разделе Последствия интроспекции аннотаций для безопасности.

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

Изменено в версии 3.14: Теперь эта функция является псевдонимом для annotationlib.get_annotations(). Ее вызов как inspect.get_annotations по-прежнему будет работать.

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

Некоторые из следующих функций возвращают объекты 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)

inspect.getattr_static(obj, attr, default)

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

inspect.CO_HAS_DOCSTRING

Флаг установлен, если в исходном коде для объекта кода есть строка документации. Если флаг установлен, она будет первым элементом в co_consts.

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

inspect.CO_METHOD

Флаг установлен, если объект кода является функцией, определённой в области видимости класса.

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

Флаги буфера

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

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