inspect — Просмотр живых объектов

Типы и члены

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

inspect.getmembers(object[, predicate])

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

Примечание

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

inspect.getmembers_static(object[, predicate])

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

Примечание

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

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

inspect.getmodulename(path)

Возвращает имя модуля, названного файлом path, без включения имён содержащих пакетов. Расширение файла проверяется по всем записям в importlib.machinery.all_suffixes(). Если оно совпадает, возвращается конечный компонент пути с удалённым расширением. В противном случае, возвращается None.

Обратите внимание, что эта функция только возвращает осмысленное имя для фактических модулей Python — пути, потенциально относящиеся к пакетам Python, всё ещё будут возвращать None.

Изменено в версии 3.3: Функция основана непосредственно на importlib.

inspect.ismodule(object)

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

inspect.isclass(object)

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

inspect.ismethod(object)

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

inspect.isfunction(object)

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

inspect.isgeneratorfunction(object)

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

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

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

inspect.isgenerator(object)

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

inspect.iscoroutinefunction(object)

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

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

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

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

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

inspect.markcoroutinefunction(func)

Декоратор для маркировки вызываемого объекта как функции-генератора корутины, если это не будет обнаружено iscoroutinefunction().

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

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

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

inspect.iscoroutine(object)

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

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

inspect.isawaitable(object)

Возвращает True если объект может быть использован в выражении await.

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

import types

def gen():
    yield
@types.coroutine
def gen_coro():
    yield

assert not isawaitable(gen())
assert isawaitable(gen_coro())

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

inspect.isasyncgenfunction(object)

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

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

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

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

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

inspect.isasyncgen(object)

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

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

inspect.istraceback(object)

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

inspect.isframe(object)

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

inspect.iscode(object)

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

inspect.isbuiltin(object)

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

inspect.ismethodwrapper(object)

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

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

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

inspect.isroutine(object)

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

inspect.isabstract(object)

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

inspect.ismethoddescriptor(object)

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

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

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

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

inspect.isdatadescriptor(object)

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

Описатели данных имеют метод __set__ или метод __delete__. Примеры – свойства (определенные в Python), getsets и члены. Последние два определены в C, и для этих типов доступны более конкретные тесты, которые устойчивы к различным реализациям Python. Обычно описатели данных также будут иметь атрибуты __name__ и __doc__, (свойства, getsets и члены имеют оба этих атрибута), но это не гарантируется.

inspect.isgetsetdescriptor(object)

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

Подробность реализации CPython: getsets — это атрибуты, определенные в модулях расширения через структуры 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

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

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

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

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

Примечание

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

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

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

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

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

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

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

Изменено в версии 3.5: Объекты Signature теперь сериализуются и являются хэшируемыми.

empty

Специальный маркер на уровне класса для указания отсутствия аннотации возвращаемого значения.

parameters

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

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

return_annotation

Аннотация «возврата» для вызываемого объекта. Если у вызываемого объекта нет аннотации «возврата», этот атрибут устанавливается в Signature.empty.

bind(*args, **kwargs)

Создаёт отображение позиционных и именованных аргументов параметрам. Возвращает BoundArguments, если *args и **kwargs соответствуют сигнатуре, или вызывает TypeError.

bind_partial(*args, **kwargs)

Действует так же, как Signature.bind(), но позволяет пропускать некоторые обязательные аргументы (имитирует поведение functools.partial()). Возвращает BoundArguments, или вызывает TypeError, если переданные аргументы не соответствуют сигнатуре.

replace(*[, parameters][, return_annotation])

Создаёт новый экземпляр Signature на основе экземпляра, на котором был вызван метод replace(). Можно передать другие parameters и/или return_annotation, чтобы переопределить соответствующие свойства базовой сигнатуры. Для удаления return_annotation из скопированной Signature, передайте Signature.empty.

>>> def test(a, b):
...     pass
...
>>> sig = signature(test)
>>> new_sig = sig.replace(return_annotation="new return anno")
>>> str(new_sig)
"(a, b) -> 'new return anno'"

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

format(*, max_width=None)

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

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

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

classmethod from_callable(obj, *, follow_wrapped=True, globals=None, locals=None, eval_str=False)

Возвращает объект Signature (или его подкласс) для данного вызываемого объекта obj.

Этот метод упрощает наследование от Signature:

class MySignature(Signature):
    pass
sig = MySignature.from_callable(sum)
assert isinstance(sig, MySignature)

В противном случае его поведение идентично поведению signature().

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

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

class inspect.Parameter(name, kind, *, default=Parameter.empty, annotation=Parameter.empty)

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

Изменено в версии 3.5: Объекты параметра теперь сериализуемы и хешируемы.

empty

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

name

Имя параметра в виде строки. Имя должно быть допустимым идентификатором Python.

Деталь реализации CPython: CPython генерирует неявные имена параметров вида .0 для кодовых объектов, используемых для реализации comprehensions и generator expressions.

Изменено в версии 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 на основе экземпляра, на котором вызывался метод. Для переопределения атрибута Parameter, передайте соответствующий аргумент. Для удаления значения по умолчанию и/или аннотации из Parameter, передайте Parameter.empty.

>>> from inspect import Parameter
>>> param = Parameter('foo', Parameter.KEYWORD_ONLY, default=42)
>>> str(param)
'foo=42'

>>> str(param.replace()) # Will create a shallow copy of 'param'
'foo=42'

>>> str(param.replace(default=Parameter.empty, annotation='spam'))
"foo: 'spam'"

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

Изменено в версии 3.4: В Python 3.3 объекты Parameter разрешалось иметь name установленным в None если их kind было установлено в POSITIONAL_ONLY. Это больше не разрешается.

class inspect.BoundArguments

Результат вызова Signature.bind() или Signature.bind_partial(). Содержит сопоставление аргументов с параметрами функции.

arguments

Изменяемое отображение имён параметров на значения аргументов. Содержит только явно привязанные аргументы. Изменения в arguments будут отражаться в args и kwargs.

Должен использоваться совместно с Signature.parameters для любых целей обработки аргументов.

Примечание

Аргументы, для которых Signature.bind() или Signature.bind_partial() полагались на значение по умолчанию, пропускаются. Однако, при необходимости, используйте BoundArguments.apply_defaults() для их добавления.

Изменено в версии 3.9: arguments теперь имеет тип dict. Раньше он был типа collections.OrderedDict.

args

Кортеж значений позиционных аргументов. Динамически вычисляется из атрибута arguments.

kwargs

Словарь значений ключевых аргументов. Динамически вычисляется из атрибута arguments. Аргументы, которые могут быть переданы позиционно, включены в args вместо этого.

signature

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

apply_defaults()

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

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

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

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

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

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

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

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

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

inspect.getclasstree(classes, unique=False)

Расположите заданный список классов в иерархии вложенных списков. Где появляется вложенный список, он содержит классы, производные от класса, запись которого непосредственно предшествует списку. Каждая запись — это 2-кортеж, содержащий класс и кортеж его базовых классов. Если аргумент unique имеет значение true, в возвращаемой структуре для каждого класса в заданном списке появляется ровно одна запись. В противном случае классы, использующие множественное наследование, и их потомки будут появляться несколько раз.

inspect.getfullargspec(func)

Получить имена и значения по умолчанию параметров Python-функции. Возвращается именованный кортеж:

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

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

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

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

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

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

inspect.getargvalues(frame)

Получить информацию об аргументах, переданных в определённую область. Возвращается именованный кортеж ArgInfo(args, varargs, keywords, locals). args — список имён аргументов. varargs и keywords — имена * и ** аргументов или None. locals — словарь локальных переменных данной области.

Примечание

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

inspect.formatargvalues(args[, varargs, varkw, locals, formatarg, formatvarargs, formatvarkw, formatvalue])

Форматировать красивое представление спецификации аргументов из четырёх значений, возвращаемых getargvalues(). Аргументы *format — соответствующие необязательные функции форматирования, которые вызываются для преобразования имён и значений в строки.

Примечание

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

inspect.getmro(cls)

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

inspect.getcallargs(func, /, *args, **kwds)

Связывает args и kwds с именами аргументов Python-функции или метода func, как если бы она была вызвана с ними. Для связанных методов также связывает первый аргумент (обычно именованный self) с соответствующим экземпляром. Возвращается словарь, сопоставляющий имена аргументов (включая имена * и ** аргументов, если они есть) со значениями из args и kwds. В случае неверного вызова func, то есть всякий раз, когда func(*args, **kwds) вызовет исключение из-за несовместимой подписи, поднимается исключение того же типа и с тем же или похожим сообщением. Например:

>>> from inspect import getcallargs
>>> def f(a, b=1, *pos, **named):
...     pass
...
>>> getcallargs(f, 1, 2, 3) == {'a': 1, 'named': {}, 'b': 2, 'pos': (3,)}
True
>>> getcallargs(f, a=2, x=4) == {'a': 2, 'named': {'x': 4}, 'b': 1, 'pos': ()}
True
>>> getcallargs(f)
Traceback (most recent call last):
...
TypeError: f() missing 1 required positional argument: 'a'

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

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

inspect.getclosurevars(func)

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

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

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

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

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

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

ValueError генерируется, если встречена циклическая зависимость.

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

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

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

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

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

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

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

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

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

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

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

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