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

Типы и члены

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

inspect.getmembers(object[, predicate])

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

Примечание

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

inspect.getmodulename(path)

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

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

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

inspect.ismodule(object)

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

inspect.isclass(object)

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

inspect.ismethod(object)

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

inspect.isfunction(object)

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

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

inspect.isgetsetdescriptor(object)

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

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

inspect.ismemberdescriptor(object)

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

Деталь реализации CPython: Описатели member являются атрибутами, определенными в модулях расширения с помощью структур 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: OSError генерируется вместо IOError, которая теперь является псевдонимом для неё.

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

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

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

Примечание

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

Изменено в версии 3.9: arguments теперь имеет тип dict. Раньше он был типа collections.OrderedDict.

args

Кортеж значений позиционных аргументов. Динамически вычисляется из атрибута arguments.

kwargs

Словарь значений ключевых аргументов. Динамически вычисляется из атрибута arguments.

signature

Ссылка на родительский объект Signature.

apply_defaults()

Устанавливает значения по умолчанию для отсутствующих аргументов.

Для аргументов переменной длины (*args) значением по умолчанию является пустой кортеж.

Для аргументов переменной длины с ключевыми словами (**kwargs) значением по умолчанию является пустой словарь.

>>> def foo(a, b='ham', *args): pass
>>> ba = inspect.signature(foo).bind('spam')
>>> ba.apply_defaults()
>>> ba.arguments
{'a': 'spam', 'b': 'ham', 'args': ()}

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

Свойства args и kwargs могут использоваться для вызова функций:

def test(a, *, b):
    ...

sig = signature(test)
ba = sig.bind(10, b=20)
test(*ba.args, **ba.kwargs)

Классы и функции

inspect.getclasstree(classes, unique=False)

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

inspect.getargspec(func)

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

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

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

inspect.getfullargspec(func)

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

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

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

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

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

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

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

inspect.getargvalues(frame)

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

Примечание

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

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

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

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

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

Например:

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

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

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

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

Примечание

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

inspect.getmro(cls)

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

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

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

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

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

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

inspect.getclosurevars(func)

Получить сопоставление внешних ссылок на имена в Python-функции или -методе func с их текущими значениями. Возвращается именованный кортеж ClosureVars(nonlocals, globals, builtins, unbound). nonlocals сопоставляет имена, на которые есть ссылки, с переменными лексического закрытия, globals — с глобальными переменными модуля функции и builtins — со встроенными переменными, видимыми из тела функции. unbound — множество имён, на которые есть ссылки в функции, но которые не могут быть разрешены при учёте текущих глобальных переменных модуля и встроенных переменных.

TypeError генерируется, если func не является Python-функцией или -методом.

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

inspect.unwrap(func, *, stop=None)

Получить объект, обернутый func. Он отслеживает цепочку __wrapped__ атрибутов, возвращая последний объект в цепочке.

stop — необязательная функция обратного вызова, принимающая в качестве единственного аргумента объект в цепочке оберток, которая позволяет завершить процесс распечатывания раньше, если функция обратного вызова возвращает истинное значение. Если функция обратного вызова никогда не возвращает истинное значение, то как обычно возвращается последний объект в цепочке. Например, signature() использует это для прекращения распечатывания, если у какого-либо объекта в цепочке определён __signature__ атрибут.

ValueError генерируется, если обнаружена циклическая зависимость.

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

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

При возвращении следующих функций «записей стека», каждая запись — это именованная кортеж 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, и могут преобразовываться в объекты корутин yield from. Дополнительные сведения см. в PEP 492.

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

inspect.CO_ASYNC_GENERATOR

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

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

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

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

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

--details

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