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

Исходный код: Lib/inspect.py

Модуль 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, включая функции, созданные с помощью выражения лямбда.

inspect.isgeneratorfunction(object)

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

inspect.isgenerator(object)

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

inspect.iscoroutinefunction(object)

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

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

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.

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 , если объект является описателем данных.

Описатели данных имеют как метод __get__, так и метод __set__. Примерами являются свойства (определенные в 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(). Если строка документации для объекта не предоставлена, а объект является классом, методом, свойством или описателем, извлекает строку документации из иерархии наследования.

Изменено в версии 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 (бывший alias).

inspect.getsource(object)

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

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

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

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

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

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

Флаги кодовых объектов модуля inspect

Кодовые объекты 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

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