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), functools.partial(), оборачивающей функцию-сопрограмму, или синхронной функцией, помеченной с помощью markcoroutinefunction().

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

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

Изменено в версии 3.12: Теперь синхронные функции, помеченные с помощью markcoroutinefunction(), возвращают 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, если обёрнутая функция является функцией асинхронного генератора.

inspect.isasyncgen(object)

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

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

inspect.istraceback(object)

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

inspect.isframe(object)

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

inspect.iscode(object)

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

inspect.isbuiltin(object)

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

inspect.ismethodwrapper(object)

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

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

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

inspect.isroutine(object)

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

inspect.isabstract(object)

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

inspect.ismethoddescriptor(object)

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

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

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

inspect.isdatadescriptor(object)

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

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

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

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

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

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

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

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

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

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

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

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

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