`inspect` — Осмотреть живые объекты¶

Источник: Lib/inspect.py

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

Существует четыре основных вида услуг, предоставляемых этим модулем: проверка типов, получение исходного кода, проверка классов и функций, а также проверка стека интерпретатора.

Типы и члены¶

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

Тип	Атрибут	Описание
класс	__doc__	строка документации
	__name__	имя, под которым был определен этот класс
	__qualname__	квалифицированное имя
	__модуль__	имя модуля, в котором был определен этот класс
	__type_params__	Кортеж, содержащий type parameters общего класса
метод	__doc__	строка документации
	__name__	имя, под которым был определен этот метод
	__qualname__	квалифицированное имя
	__func__	объект функции, содержащий реализацию метода
	__self__	экземпляр, к которому привязан этот метод, или `None`
	__модуль__	имя модуля, в котором был определен этот метод
функция	__doc__	строка документации
	__name__	имя, под которым была определена эта функция
	__qualname__	квалифицированное имя
	__код__	объект кода, содержащий скомпилированную функцию bytecode
	__defaults__	кортеж любых значений по умолчанию для позиционных или ключевых параметров
	__kwdefaults__	отображение любых значений по умолчанию для параметров, относящихся только к ключевым словам
	__globals__	глобальное пространство имен, в котором была определена эта функция
	__builtins__	пространство имен builtins
	__аннотации__	сопоставление имен параметров с аннотациями; ключ `"return"` зарезервирован для возвратных аннотаций.
	__type_params__	Кортеж, содержащий type parameters общей функции
	__модуль__	имя модуля, в котором была определена эта функция
traceback	tb_frame	объект кадра на этом уровне
	tb_lasti	индекс последней попытки выполнения инструкции в байткоде
	tb_lineno	номер текущей строки в исходном коде Python
	tb_next	следующий внутренний объект трассировки (вызываемый на этом уровне)
рама	f_back	следующий объект внешнего кадра (вызывающий этот кадр)
	f_builtins	пространство имен builtins, видимое этим кадром
	f_code	объект кода, выполняемый в этом кадре
	f_globals	глобальное пространство имен, видимое этим кадром
	f_lasti	индекс последней попытки выполнения инструкции в байткоде
	f_lineno	номер текущей строки в исходном коде Python
	f_locals	локальное пространство имен, видимое этим кадром
	f_trace	функция трассировки для этого кадра, или `None`
код	co_argcount	количество аргументов (не включая аргументы, содержащие только ключевые слова, * или ** аргументы)
	код	строка необработанного скомпилированного байткода
	co_cellvars	кортеж имен переменных ячеек (на которые ссылаются содержащие диапазоны)
	co_consts	кортеж констант, используемых в байткоде
	co_filename	имя файла, в котором был создан этот объект кода
	co_firstlineno	номер первой строки в исходном коде Python
	co_flags	растровое изображение `CO_*` флагов, читать далее here
	co_lnotab	кодированное отображение номеров строк на индексы байткода
	co_freevars	кортеж имен свободных переменных (на которые можно ссылаться через закрытие функции)
	co_posonlyargcount	количество только позиционных аргументов
	co_kwonlyargcount	количество аргументов, содержащих только ключевые слова (не включая ** arg)
	совместное имя	имя, под которым был определен данный объект кода
	co_qualname	полное имя, с которым был определен этот объект кода
	совместные имена	кортеж имен, отличных от аргументов и локалей функции
	co_nlocals	количество локальных переменных
	co_stacksize	Необходимое место в стеке виртуальной машины
	co_varnames	кортеж имен аргументов и локальных переменных
генератор	__name__	имя
	__qualname__	квалифицированное имя
	gi_frame	рама
	gi_running	Генератор работает?
	gi_code	код
	gi_yieldfrom	объект, итерируемый по `yield from`, или `None`
coroutine	__name__	имя
	__qualname__	квалифицированное имя
	cr_await	объект, которого ожидают, или `None`
	cr_frame	рама
	cr_running	выполняется ли корутина?
	cr_code	код
	cr_origin	где была создана coroutine, или `None`. См. `sys.set_coroutine_origin_tracking_depth()`
встроенный	__doc__	строка документации
	__name__	оригинальное имя этой функции или метода
	__qualname__	квалифицированное имя
	__self__	экземпляр, к которому привязан метод, или `None`

Изменено в версии 3.5: Добавьте атрибуты __qualname__ и gi_yieldfrom к генераторам.

Атрибут __name__ генераторов теперь устанавливается из имени функции, а не из имени кода, и теперь его можно изменить.

Изменено в версии 3.7: Добавьте атрибут cr_origin к корутинам.

Изменено в версии 3.10: Добавьте атрибут __builtins__ в функции.

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

Примечание

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

inspect.getmembers_static(object[, predicate])¶: Возвращает все члены объекта в виде списка пар (name, value), отсортированных по имени, не вызывая динамического поиска по протоколу дескрипторов, __getattr__ или __getattribute__. Опционально можно возвращать только те члены, которые удовлетворяют заданному предикату.

Примечание

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

Added in version 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, если объект является coroutine function (функцией, определенной с помощью синтаксиса async def), functools.partial(), обертывающей coroutine function, или функцией синхронизации, отмеченной markcoroutinefunction().

Added in version 3.5.

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

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

Изменено в версии 3.13: Функции, обернутые в functools.partialmethod(), теперь возвращают True, если обернутая функция является coroutine function.

inspect.markcoroutinefunction(func)¶

Декоратор для обозначения вызываемого объекта как coroutine function, если в противном случае он не будет обнаружен iscoroutinefunction().

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

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

Added in version 3.12.

inspect.iscoroutine(object)¶: Возвращает True, если объект является coroutine, созданным функцией async def.

Added in version 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())

Added in version 3.5.

inspect.isasyncgenfunction(object)¶

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

>>> async def agen():
...     yield 1
...
>>> inspect.isasyncgenfunction(agen)
True

Added in version 3.6.

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

Изменено в версии 3.13: Функции, обернутые в functools.partialmethod(), теперь возвращают True, если обернутая функция является coroutine function.

inspect.isasyncgen(object)¶: Возвращает True, если объект является asynchronous generator iterator, созданным функцией asynchronous generator.

Added in version 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__().

Added in version 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), наборы и члены. Последние два типа определены в языке C, и для них существуют более специфические тесты, которые устойчивы к различным реализациям Python. Обычно дескрипторы данных также имеют атрибуты __name__ и __doc__ (свойства, гетсеты и члены имеют оба этих атрибута), но это не гарантировано.

inspect.isgetsetdescriptor(object)¶: Возвращает True, если объект является дескриптором getset.

Детали реализации CPython: Гетсеты - это атрибуты, определенные в модулях расширения через структуры 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: OSError поднимается вместо IOError, который теперь является псевдонимом первого.

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

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

inspect.cleandoc(doc)¶

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

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

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

Added in version 3.3.

Объект 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() потенциально может вызвать исключение любого типа.

Косая черта (/) в сигнатуре функции означает, что параметры перед ней являются только позиционными. Подробнее об этом см. в разделе the FAQ entry on positional-only parameters.

Изменено в версии 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. Он представляет собой аннотацию «return» вызываемого объекта.

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

Изменено в версии 3.5: Объекты Signature теперь можно мариновать, а hashable

empty¶: Специальный маркер уровня класса, указывающий на отсутствие аннотации возврата.

parameters¶: Упорядоченное отображение имен параметров на соответствующие объекты Parameter. Параметры отображаются в строгом порядке определения, включая параметры только с ключевыми словами.

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

return_annotation¶: Аннотация «return» для вызываемого объекта. Если вызываемый объект не имеет аннотации «return», этот атрибут устанавливается в 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(), который был вызван. Можно передавать различные параметры и/или возвращаемую_аннотацию, чтобы переопределить соответствующие свойства базовой сигнатуры. Чтобы удалить 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, все параметры будут располагаться в отдельных строках.

Added in version 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().

Added in version 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: Объекты параметров теперь являются picklable и hashable.

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.

Added in version 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.

signature¶: Ссылка на родительский объект Signature.

apply_defaults()¶

Установите значения по умолчанию для отсутствующих аргументов.

Для аргументов с переменной позицией (*args) по умолчанию используется пустой кортеж.

Для аргументов с переменными ключевыми словами (**kwargs) по умолчанию используется пустой dict.

>>> def foo(a, b='ham', *args): pass
>>> ba = inspect.signature(foo).bind('spam')
>>> ba.apply_defaults()
>>> ba.arguments
{'a': 'spam', 'b': 'ham', 'args': ()}

Added in version 3.5.

Свойства args и kwargs можно использовать для вызова функций:

def test(a, *, b):
    ...

sig = signature(test)
ba = sig.bind(10, b=20)
test(*ba.args, **ba.kwargs)

См.также

PEP 362 - Сигнатура функции Объект.: Подробная спецификация, детали реализации и примеры.

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

inspect.getclasstree(classes, unique=False)¶: Расположите заданный список классов в виде иерархии вложенных списков. Если появляется вложенный список, то он содержит классы, производные от класса, запись которого находится непосредственно перед списком. Каждая запись представляет собой кортеж, содержащий класс и кортеж его базовых классов. Если аргумент unique равен true, то в возвращаемой структуре будет ровно одна запись для каждого класса из данного списка. В противном случае классы, использующие множественное наследование, и их потомки будут появляться несколько раз.

inspect.getfullargspec(func)¶

Получает имена и значения по умолчанию параметров функции Python. Возвращается значение named tuple:

FullArgSpec(args, varargs, varkw, defaults, kwonlyargs, kwonlydefaults, annotations)

args - это список имен позиционных параметров. varargs - это имя параметра * или None, если произвольные позиционные аргументы не принимаются. varkw - это имя параметра ** или None, если произвольные аргументы в виде ключевых слов не принимаются. defaults - это n-кортеж значений аргументов по умолчанию, соответствующих последним n позиционным параметрам, или None, если такие значения по умолчанию не определены. kwonlyargs - список имен параметров только для ключевых слов в порядке объявления. kwonlydefaults - словарь, отображающий имена параметров из kwonlyargs на значения по умолчанию, используемые в случае отсутствия аргументов. annotations - словарь, отображающий имена параметров на аннотации. Специальный ключ "return" используется для сообщения аннотации возвращаемого значения функции (если таковая имеется).

Обратите внимание, что signature() и Signature Object предоставляют рекомендуемый API для вызываемой интроспекции и поддерживают дополнительное поведение (например, только позиционные аргументы), которое иногда встречается в API модулей расширения. Эта функция сохраняется в основном для использования в коде, который должен поддерживать совместимость с API модулей Python 2 inspect.

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

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

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

inspect.getargvalues(frame)¶: Получение информации об аргументах, переданных в конкретный фрейм. A named tuple ArgInfo(args, varargs, keywords, locals) возвращается. args - это список имен аргументов. varargs и keywords - это имена * и ** аргументов или None. locals - словарь locals данного фрейма.

Примечание

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

inspect.formatargvalues(args[, varargs, varkw, locals, formatarg, formatvarargs, formatvarkw, formatvalue])¶: Форматирует красивый аргумент spec из четырех значений, возвращаемых 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'

Added in version 3.2.

Не рекомендуется, начиная с версии 3.5: Вместо этого используйте Signature.bind() и Signature.bind_partial().

inspect.getclosurevars(func)¶

Получает отображение ссылок на внешние имена в функции или методе Python func на их текущие значения. A named tuple ClosureVars(nonlocals, globals, builtins, unbound) возвращается. nonlocals сопоставляет имена ссылок с лексическими переменными закрытия, globals - с глобальными переменными модуля функции, а builtins - со встроенными переменными, видимыми из тела функции. unbound - это набор имен, на которые ссылается функция и которые не могут быть разрешены с учетом текущих глобалов модуля и buildins.

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

Added in version 3.3.

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

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

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

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

Added in version 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 нет дикта аннотаций, возвращается пустой дикт. (Функции и методы всегда имеют дикту аннотаций; классы, модули и другие типы вызываемых объектов могут не иметь).
Игнорирует унаследованные аннотации классов. Если класс не имеет собственной дикты аннотаций, возвращается пустая дикта.
Все обращения к членам объекта и значениям dict выполняются с использованием getattr() и dict.get() для безопасности.
Всегда, всегда, всегда возвращает только что созданный dict.

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

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

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

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

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

Added in version 3.10.

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

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

class inspect.FrameInfo¶

frame¶: Номер frame object, которому соответствует запись.

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

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

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

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

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

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

Изменено в версии 3.5: Возвращает named tuple вместо tuple.

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

class inspect.Traceback¶

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

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

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

code_context¶: Список строк контекста из исходного кода, выполняемого фреймом, которому соответствует данный трассировочный откат.

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

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

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

Примечание

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

Хотя детектор циклов будет их ловить, уничтожение фреймов (и локальных переменных) можно сделать детерминированным, удалив цикл в предложении finally. Это также важно, если детектор циклов был отключен при компиляции Python или при использовании gc.disable(). Например:

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

Если вы хотите сохранить фрейм (например, чтобы позже вывести трассировку), вы также можете разорвать циклы ссылок с помощью метода frame.clear().

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

inspect.getframeinfo(frame, context=1)¶: Получение информации о кадре или объекте traceback. Возвращается объект Traceback.

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

inspect.getouterframes(frame, context=1)¶: Получает список объектов FrameInfo для кадра и всех внешних кадров. Эти фреймы представляют вызовы, которые привели к созданию фрейма. Первая запись в возвращаемом списке представляет фрейм; последняя запись представляет крайний вызов в стеке фрейма.

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

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

inspect.getinnerframes(traceback, context=1)¶: Получает список объектов FrameInfo для фрейма трассировки и всех внутренних фреймов. Эти кадры представляют вызовы, сделанные в результате выполнения кадра. Первая запись в списке представляет traceback; последняя запись представляет место, где было поднято исключение.

Изменено в версии 3.5: Возвращается список named tuples 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: Возвращается список named tuples FrameInfo(frame, filename, lineno, function, code_context, index) возвращается.

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

inspect.trace(context=1)¶: Возвращает список объектов FrameInfo для стека между текущим кадром и кадром, в котором было поднято обрабатываемое в данный момент исключение. Первая запись в списке представляет вызывающую сторону; последняя запись представляет место, где было поднято исключение.

Изменено в версии 3.5: Возвращается список named tuples 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__ затенен другим членом (например, свойством), то эта функция не сможет найти члены экземпляра.

Added in version 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: Выполнение завершено.

Added in version 3.2.

inspect.getcoroutinestate(coroutine)¶

Получение текущего состояния объекта coroutine. Функция предназначена для использования с объектами coroutine, созданными функциями async def, но может принимать любой coroutine-подобный объект, имеющий атрибуты cr_running и cr_frame.

Возможны следующие состояния:

CORO_CREATED: Ожидание начала выполнения.
CORO_RUNNING: В настоящее время выполняется интерпретатором.
CORO_SUSPENDED: В настоящее время выполнение приостановлено на выражении await.
CORO_CLOSED: Выполнение завершено.

Added in version 3.5.

inspect.getasyncgenstate(agen)¶

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

Возможны следующие состояния:

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

Added in version 3.12.

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

inspect.getgeneratorlocals(generator)¶

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

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

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

Added in version 3.3.

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

Added in version 3.5.

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

Added in version 3.12.

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

Объекты кода Python имеют атрибут co_flags, который представляет собой битовое изображение следующих флагов:

inspect.CO_OPTIMIZED¶: Код объекта оптимизирован и использует быстрые локали.

inspect.CO_NEWLOCALS¶: Если установлено, то при выполнении объекта кода для f_locals кадра будет создан новый dict.

inspect.CO_VARARGS¶: Объект кода имеет переменный позиционный параметр (*args-подобный).

inspect.CO_VARKEYWORDS¶: Объект кода имеет переменный ключевой параметр (**kwargs-подобный).

inspect.CO_NESTED¶: Флаг устанавливается, когда объект кода является вложенной функцией.

inspect.CO_GENERATOR¶: Флаг устанавливается, если объект кода является функцией-генератором, т.е. при выполнении объекта кода возвращается объект-генератор.

inspect.CO_COROUTINE¶: Флаг устанавливается, когда объект кода является коревой функцией. Когда объект кода выполняется, он возвращает объект coroutine. Более подробную информацию см. в разделе PEP 492.

Added in version 3.5.

inspect.CO_ITERABLE_COROUTINE¶: Флаг используется для преобразования генераторов в корутины на основе генераторов. Объекты генераторов с этим флагом могут использоваться в await выражениях, а объекты yield from короутинов. Более подробную информацию см. в разделе PEP 492.

Added in version 3.5.

inspect.CO_ASYNC_GENERATOR¶: Флаг устанавливается, если объект кода является функцией асинхронного генератора. При выполнении объекта кода он возвращает объект асинхронного генератора. Более подробную информацию см. в разделе PEP 525.

Added in version 3.6.

Примечание

Флаги специфичны для CPython и не могут быть определены в других реализациях Python. Кроме того, флаги являются деталями реализации и могут быть удалены или устаревшими в будущих релизах Python. Рекомендуется использовать публичные API из модуля inspect для любых потребностей в интроспекции.

Флаги буфера¶

class inspect.BufferFlags¶

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

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

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¶

Added in version 3.12.

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

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

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

--details¶: Выведите информацию об указанном объекте, а не исходный код

`inspect` — Осмотреть живые объекты¶

Типы и члены¶

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

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

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

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

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

Современное состояние генераторов, коротинов и асинхронных генераторов¶

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

Флаги буфера¶

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

Оглавление

Предыдущий раздел

Следующий раздел

inspect — Осмотреть живые объекты¶

Типы и члены¶

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

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

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

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

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

Современное состояние генераторов, коротинов и асинхронных генераторов¶

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

Флаги буфера¶

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

`inspect` — Осмотреть живые объекты¶