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

Типы и члены

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

inspect.getmembers(object[, predicate])

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

Примечание

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

inspect.isgetsetdescriptor(object)

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

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

inspect.ismemberdescriptor(object)

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

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

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

inspect.getdoc(object)

Получить строку документации для объекта, очищенную с помощью cleandoc(). Если строка документации для объекта не указана, а объект является классом, методом, свойством или дескриптором, получить строку документации из иерархии наследования.

Изменено в версии 3.5: Теперь строки документации наследуются, если не переопределены.

inspect.getcomments(object)

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

inspect.getfile(object)

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

inspect.getmodule(object)

Попытка определить, в каком модуле был определен объект.

inspect.getsourcefile(object)

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

inspect.getsourcelines(object)

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

Изменено в версии 3.3: Вместо IOError (теперь псевдоним первого) возбуждается ошибка OSError.

inspect.getsource(object)

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

Изменено в версии 3.3: Вместо IOError (теперь псевдоним первого) возбуждается ошибка OSError.

inspect.cleandoc(doc)

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

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

Просмотр вызываемых объектов с помощью объекта Signature

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

inspect.signature(callable, *, follow_wrapped=True)

Возвращает объект 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().

Возбуждает исключение ValueError, если сигнатура не может быть предоставлена, и TypeError, если этот тип объекта не поддерживается.

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

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

Примечание

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

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

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

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

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

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 было разрешено устанавливать name в None если kind было установлено в POSITIONAL_ONLY. Это больше не разрешено.

class inspect.BoundArguments

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

arguments

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

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

Примечание

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

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
OrderedDict([('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.

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

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

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

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

inspect.getinnerframes(traceback, context=1)

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

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

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