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

Типы и члены

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

inspect.getmembers(object[, predicate])

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

Примечание

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

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).

Введено в версии 3.5.

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

inspect.iscoroutine(object)

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

Введено в версии 3.5.

inspect.isawaitable(object)

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

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

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.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() попытается автоматически разпарсить аннотации с помощью inspect.get_annotations(). Параметры global, locals, и eval_str передаются в inspect.get_annotations() при разрешении аннотаций; см. документацию для inspect.get_annotations() для инструкций по использованию этих параметров.

Возбуждает ValueError, если сигнатура не может быть предоставлена, и TypeError, если объект данного типа не поддерживается. Также, если аннотации строковые, а eval_str не ложно, вызовы eval() для разбора аннотаций могут потенциально вызвать любые виды исключений.

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

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

Новая версия с 3.10: параметры globals, locals, и eval_str.

Примечание

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

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 для переопределения соответствующих свойств сигнатуры-источника. Для удаления аннотации возвращаемого значения из скопированной сигнатуры, передайте 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, globalns=None, localns=None)

Возвращает объект Signature (или его подкласс) для заданного вызываемого объекта obj. Передайте follow_wrapped=False для получения сигнатуры obj без распаковки его цепочки __wrapped__. globalns и localns будут использоваться как пространства имён при разрешении аннотаций.

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

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

Новая версия с 3.5.

Новая версия с 3.10: параметры globalns и localns.

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

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

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

empty

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

name

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

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

Изменено в версии 3.6: Эти имена параметров представлены в данном модуле как имена типа implicit0.

default

Значение по умолчанию для параметра. Если параметр не имеет значения по умолчанию, этот атрибут установлен в Parameter.empty.

annotation

Аннотация для параметра. Если параметр не имеет аннотации, этот атрибут установлен в Parameter.empty.

kind

Описывает, как значения аргументов привязываются к параметру. Возможные значения доступны через Parameter (например, Parameter.KEYWORD_ONLY), и поддерживают сравнение и упорядочение в следующем порядке:

Имя	Значение
POSITIONAL_ONLY	Значение должно быть передано в качестве позиционного аргумента. Позиционные параметры — это те, которые появляются перед записью / (если она присутствует) в определении функции Python.
POSITIONAL_OR_KEYWORD	Значение может быть передано как ключевой или позиционный аргумент (это стандартное поведение привязки для функций, реализованных на Python).
VAR_POSITIONAL	Кортеж позиционных аргументов, которые не привязаны к какому-либо другому параметру. Соответствует параметру *args в определении функции Python.
KEYWORD_ONLY	Значение должно быть передано как ключевой аргумент. Ключевые параметры — это те, которые появляются после записи * или *args в определении функции Python.
VAR_KEYWORD	Словарь ключевых аргументов, которые не привязаны к какому-либо другому параметру. Соответствует параметру **kwargs в определении функции Python.

Пример: вывести все ключевые аргументы без значений по умолчанию:

>>> def foo(a, b, *, c, d=10):
...     pass

>>> sig = signature(foo)
>>> for param in sig.parameters.values():
...     if (param.kind == param.KEYWORD_ONLY and
...                        param.default is param.empty):
...         print('Parameter:', param)
Parameter: c

kind.description

Описание перечисления значений Parameter.kind.

Новое в версии 3.8.

Пример: вывести все описания аргументов:

>>> def foo(a, b, *, c, d=10):
...     pass

>>> sig = signature(foo)
>>> for param in sig.parameters.values():
...     print(param.kind.description)
positional or keyword
positional or keyword
keyword-only
keyword-only

replace(*[, name][, kind][, default][, annotation])

Создаёт новый объект Parameter, базируясь на экземпляре, на котором вызов был произведён. Для переопределения атрибута 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.getargspec(func)

Получить имена и значения по умолчанию параметров функции Python. Возвращается именованный кортеж ArgSpec(args, varargs, keywords, defaults). args — список имён параметров. varargs и keywords — имена параметров * и ** или None. defaults — кортеж значений параметров по умолчанию или None если параметров по умолчанию нет; если этот кортеж имеет n элементов, они соответствуют последним n элементам в args.

Устарело начиная с версии 3.0: Используйте getfullargspec() для обновлённого API, который обычно является прямым заменой, но также правильно обрабатывает аннотации функций и параметры только для ключевых слов.

В качестве альтернативы используйте signature() и Объект Signature, которые предоставляют более структурированный API для интроспекции вызываемых объектов.

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.formatargspec(args[, varargs, varkw, defaults, kwonlyargs, kwonlydefaults, annotations[, formatarg, formatvarargs, formatvarkw, formatvalue, formatreturns, formatannotations]])

Форматировать красивое описание аргументов из значений, возвращаемых getfullargspec().

Первые семь аргументов (args, varargs, varkw, defaults, kwonlyargs, kwonlydefaults, annotations).

Остальные шесть аргументов — функции, вызываемые для преобразования имён аргументов, * имени аргумента, ** имени аргумента, значений по умолчанию, аннотации возврата и индивидуальных аннотаций в строки, соответственно.

Например:

>>> from inspect import formatargspec, getfullargspec
>>> def f(a: int, b: float):
...     pass
...
>>> formatargspec(*getfullargspec(f))
'(a: int, b: float)'

Устарело начиная с версии 3.5: Используйте signature() и Объект Signature, которые предоставляют лучший API для интроспекции вызываемых объектов.

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 — необязательный обратный вызов, принимающий в качестве единственного аргумента объект в цепочке обёрток, который позволяет прервать процесс распаковки, если обратный вызов возвращает истинное значение. Если обратный вызов никогда не возвращает истинное значение, в качестве обычного значения возвращается последний объект в цепочке. Например, 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(frame, filename, lineno, function, code_context, index). Кортеж содержит объект кадра, имя файла, номер строки текущей строки, имя функции, список строк контекста из исходного кода и индекс текущей строки в этом списке.

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

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

inspect.getframeinfo(frame, context=1)

Получить информацию о кадре или объекте трассировки. Возвращается именованный кортеж Traceback(filename, lineno, function, code_context, index).

inspect.getouterframes(frame, context=1)

Получить список записей кадра для кадра и всех внешних кадров. Эти кадры представляют вызовы, которые привели к созданию frame. Первая запись в возвращаемом списке представляет frame; последняя запись представляет внешний вызов в стеке frame.

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

inspect.getinnerframes(traceback, context=1)

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

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

inspect.currentframe()

Возвращает объект кадра для вызывающего стека фреймов.

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

inspect.stack(context=1)

Возвращает список записей кадров для стека вызывающей стороны. Первая запись в возвращаемом списке представляет вызывающую сторону; последняя запись представляет внешний вызов в стеке.

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

inspect.trace(context=1)

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

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

Статическое извлечение атрибутов

Как 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.getgeneratorlocals(generator)

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

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

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

Новое в версии 3.3.

inspect.getcoroutinelocals(coroutine)

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

Новое в версии 3.5.

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

Объекты кода 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_NOFREE

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

inspect.CO_COROUTINE

Флаг установлен, когда объект кода — это функция корутины. При выполнении объекта кода возвращается объект корутины. Подробнее см. PEP 492.

Новое в версии 3.5.

inspect.CO_ITERABLE_COROUTINE

Флаг используется для преобразования генераторов в генераторные корутины. Объекты генераторов с этим флагом могут использоваться в выражениях await, и могут быть преобразованы в объекты корутины. Подробнее см. PEP 492.

Новое в версии 3.5.

inspect.CO_ASYNC_GENERATOR

Флаг установлен, когда объект кода — это функция асинхронного генератора. При выполнении объекта кода возвращается объект асинхронного генератора. Подробнее см. PEP 525.

Новое в версии 3.6.

Командная строка

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

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

--details

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