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

Типы и члены

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

inspect.getmembers(object[, predicate])

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

Примечание

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

inspect.getmembers_static(object[, predicate])

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

Примечание

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

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

inspect.getmodulename(path)

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

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

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

inspect.ismodule(object)

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

inspect.isclass(object)

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

inspect.ismethod(object)

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

inspect.isfunction(object)

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

inspect.isgeneratorfunction(object)

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

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

inspect.isgenerator(object)

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

inspect.iscoroutinefunction(object)

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

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

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

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

inspect.markcoroutinefunction(func)

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

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

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

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

inspect.iscoroutine(object)

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

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

inspect.isawaitable(object)

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

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

import types

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

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

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

inspect.isasyncgenfunction(object)

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

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

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

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

inspect.isasyncgen(object)

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

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

inspect.istraceback(object)

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

inspect.isframe(object)

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

inspect.iscode(object)

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

inspect.isbuiltin(object)

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

inspect.ismethodwrapper(object)

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

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

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

inspect.isroutine(object)

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

inspect.isabstract(object)

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

inspect.ismethoddescriptor(object)

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

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

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

inspect.isdatadescriptor(object)

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

Описатели данных имеют метод __set__ или метод __delete__. Примеры — свойства (определённые в Python), 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 для данного callable:

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

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

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

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

Примечание

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

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

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

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

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

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

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

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

empty

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

parameters

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

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

return_annotation

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

bind(*args, **kwargs)

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

bind_partial(*args, **kwargs)

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

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

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

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

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

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

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

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

Его поведение в остальном идентично поведению signature().

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

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

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

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

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

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'"

Изменено в версии 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) значение по умолчанию — пустой словарь.

>>> 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 модулей расширения. Данная функция сохраняется в основном для использования в коде, которому требуется сохранять совместимость с Python 2 inspect модулем API.

Изменено в версии 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)

Получить информацию об аргументах, переданных в определённую область. Возвращается именованный кортеж 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 для кадра и всех внешних кадров. Эти кадры представляют вызовы, которые привели к созданию кадра. Первый элемент в возвращаемом списке представляет кадр; последний элемент представляет внешний вызов в стеке кадра.

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

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

inspect.getinnerframes(traceback, context=1)

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

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

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