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

Типы и члены¶

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

inspect.getmembers(object[, predicate])¶

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

Примечание

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, если объект является coroutine function (функция, определенная с синтаксисом async def).

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

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

inspect.iscoroutine(object)¶

Возвращает True, если объект является coroutine, созданным функцией 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, если объект является asynchronous generator функцией, например:

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

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

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

inspect.isasyncgen(object)¶

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

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

inspect.isgetsetdescriptor(object)¶

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

CPython implementation detail: getsets - это атрибуты, определенные в модулях расширения через структуры PyGetSetDef. Для реализаций Python, не имеющих таких типов, этот метод всегда будет возвращать False.

inspect.ismemberdescriptor(object)¶

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

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

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

inspect.getsource(object)¶

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

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

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

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

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

Изменено в версии 3.5: Объекты подписи являются picklable и hashable.

empty¶

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

parameters¶

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

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

return_annotation¶

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

bind(*args, **kwargs)¶

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

bind_partial(*args, **kwargs)¶

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

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

Создает новый экземпляр Signature на основе экземпляра, для которого была вызвана функция replace. Можно передавать различные parameters и/или return_annotation, чтобы переопределить соответствующие свойства базовой сигнатуры. Чтобы удалить 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: Объекты параметров являются picklable и hashable.

empty¶

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

name¶

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

CPython implementation detail: 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 на основе экземпляра, для которого была вызвана функция replaced. Чтобы переопределить атрибут 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) по умолчанию используется пустой dict.

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

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

inspect.getargspec(func)¶

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

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

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

inspect.getfullargspec(func)¶

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

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

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

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

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

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

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

inspect.getargvalues(frame)¶

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

Примечание

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

inspect.formatargspec(args[, varargs, varkw, defaults, kwonlyargs, kwonlydefaults, annotations[, formatarg, formatvarargs, formatvarkw, formatvalue, formatreturns, formatannotations]])¶

Форматирование красивого аргумента spec из значений, возвращаемых командой 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 Object, которые обеспечивают лучший API интроспекции для вызываемых таблиц.

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

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

Примечание

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

inspect.getmro(cls)¶

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

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

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

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

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

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

inspect.getclosurevars(func)¶

Получить отображение ссылок на внешние имена в функции или методе Python func на их текущие значения. Возвращается named tuple 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() возвращает новый dict при каждом вызове; если вызвать его дважды на одном и том же объекте, он вернет два разных, но эквивалентных dict.

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

• Если eval_str равно true, то значения типа str будут нестрого структурированы с помощью eval(). Это предназначено для использования со строковыми аннотациями (from __future__ import annotations).

• Если obj не имеет диктата аннотаций, возвращает пустой дикт. (Функции и методы всегда имеют дикту аннотаций; классы, модули и другие типы вызываемых объектов могут не иметь).

• Игнорирует унаследованные аннотации классов. Если класс не имеет собственного dict аннотаций, возвращается пустой dict.

• Все доступы к членам объекта и значениям dict выполняются с использованием getattr() и dict.get() для безопасности.

• Всегда, всегда, всегда возвращает только что созданный dict.

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

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

• Если eval_str равен false (по умолчанию), значения типа str остаются неизменными.

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

• Если obj является модулем, globals по умолчанию принимает значение obj.__dict__.

• Если obj является классом, globals по умолчанию используется sys.modules[obj.__module__].__dict__, а locals по умолчанию используется пространство имен класса obj.

• Если obj является вызываемой функцией, globals по умолчанию используется obj.__globals__, хотя если obj является обернутой функцией (с помощью functools.update_wrapper()), она сначала разворачивается.

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

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

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

Когда следующие функции возвращают «записи кадров», каждая запись представляет собой кортеж named tuple 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)¶

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

inspect.getouterframes(frame, context=1)¶

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

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

inspect.getinnerframes(traceback, context=1)¶

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

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

inspect.currentframe()¶

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

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

inspect.stack(context=1)¶

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

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

inspect.trace(context=1)¶

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

Изменено в версии 3.5: Возвращается список named tuples 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: В настоящее время приостановлено на выражении доходности.

• GEN_CLOSED: Выполнение завершено.

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

inspect.getcoroutinestate(coroutine)¶

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

Возможными состояниями являются:

• CORO_CREATED: Ожидание начала выполнения.

• CORO_RUNNING: В настоящее время выполняется интерпретатором.

• CORO_SUSPENDED: В настоящее время приостановлено на выражении await.

• CORO_CLOSED: Выполнение завершено.

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

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

inspect.getgeneratorlocals(generator)¶

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

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

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

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

inspect.getcoroutinelocals(coroutine)¶

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

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

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

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

inspect.CO_OPTIMIZED¶

Кодовый объект оптимизирован, в нем используются быстрые локали.

inspect.CO_NEWLOCALS¶

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

inspect.CO_VARARGS¶

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

inspect.CO_VARKEYWORDS¶

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

inspect.CO_NESTED¶

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

inspect.CO_GENERATOR¶

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

inspect.CO_NOFREE¶

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

inspect.CO_COROUTINE¶

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

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

inspect.CO_ITERABLE_COROUTINE¶

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

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

inspect.CO_ASYNC_GENERATOR¶

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

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

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

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

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

--details¶

Печать информации об указанном объекте вместо исходного кода