inspect – Инспекция живых объектов¶inspect – Inspect live objects

Типы и члены¶Types and members

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

inspect.getmembers(object[, predicate])¶

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

Примечание

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

inspect.getmodulename(path)¶

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

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

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

inspect.ismodule(object)¶

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

inspect.isclass(object)¶

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

inspect.ismethod(object)¶

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

inspect.isfunction(object)¶

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

inspect.isgeneratorfunction(object)¶

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

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

inspect.isgenerator(object)¶

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

inspect.iscoroutinefunction(object)¶

Return True if the object is a coroutine function (a function defined with an async def syntax).

Новое в версии 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.

Changed in version 3.8: Functions wrapped in functools.partial() now return True if the wrapped function is a asynchronous generator function.

inspect.isasyncgen(object)¶

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

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

inspect.istraceback(object)¶

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

inspect.isframe(object)¶

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

inspect.iscode(object)¶

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

inspect.isbuiltin(object)¶

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

inspect.isroutine(object)¶

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

inspect.isabstract(object)¶

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

inspect.ismethoddescriptor(object)¶

Возвращает True, если объект является дескриптором метода, но не если ismethod(), isclass(), isfunction() или isbuiltin() истинны.

Это верно, например, для int.__add__. Объект, проходящий эту проверку, имеет метод __get__(), но не имеет метода __set__(), однако помимо этого набор атрибутов различается. Атрибут __name__ обычно имеет смысл, а __doc__ часто – тоже.

Методы, реализованные через дескрипторы, которые также проходят один из других тестов, возвращают False из теста ismethoddescriptor(), просто потому что другие тесты обещают больше – например, можно рассчитывать на наличие атрибута __func__ (и т.д.), когда объект проходит ismethod().

inspect.isdatadescriptor(object)¶

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

Дескрипторы данных имеют метод __set__ или __delete__. Примеры: свойства (определённые в Python), getsets и members. Последние два определены в C, и для этих типов существуют более специфичные проверки, которые надёжны в разных реализациях Python. Обычно дескрипторы данных также имеют атрибуты __name__ и __doc__ (свойства, getsets и members имеют оба этих атрибута), но это не гарантируется.

inspect.isgetsetdescriptor(object)¶

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

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

inspect.ismemberdescriptor(object)¶

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

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

Получение исходного кода¶Retrieving source code

inspect.getdoc(object)¶

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

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

inspect.getcomments(object)¶

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

inspect.getfile(object)¶

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

inspect.getmodule(object)¶

Пытается определить модуль, в котором определён объект. Возвращает None, если модуль не удаётся определить.

inspect.getsourcefile(object)¶

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

inspect.getsourcelines(object)¶

Возвращает список строк исходного кода и номер начальной строки для объекта. Аргументом может быть модуль, класс, метод, функция, traceback, frame или code-объект. Исходный код возвращается в виде списка строк этого объекта, а номер строки указывает положение первой строки кода в исходном файле. Вызывается исключение OSError, если исходный код не удаётся получить. Вызывается TypeError, если объект – встроенный модуль, класс или функция.

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

inspect.getsource(object)¶

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

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

inspect.cleandoc(doc)¶

Убирает отступы из docstrings, которые выровнены с блоками кода.

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

Интроспекция вызываемых объектов с помощью объекта Signature¶Introspecting callables with the Signature object

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

inspect.signature(callable, *, follow_wrapped=True, globals=None, locals=None, eval_str=False)¶

Возвращает объект Signature для заданного callable:

>>> from inspect import signature
>>> def foo(a, *, b:int, **kwargs):
...     pass

>>> sig = signature(foo)

>>> str(sig)
'(a, *, b:int, **kwargs)'

>>> str(sig.parameters['b'])
'b:int'

>>> sig.parameters['b'].annotation
<class 'int'>

Принимает широкий спектр вызываемых объектов Python: от обычных функций и классов до объектов functools.partial().

Для объектов, определённых в модулях, использующих строковые аннотации (from __future__ import annotations), signature() будет пытаться автоматически преобразовать их из строк с помощью inspect.get_annotations(). Параметры global, locals и eval_str передаются в inspect.get_annotations() при разрешении аннотаций; за инструкциями по использованию этих параметров обращайтесь к документации inspect.get_annotations().

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

Косая черта (/) в сигнатуре функции означает, что параметры до неё являются только позиционными. За дополнительной информацией обращайтесь к вопросу FAQ о только позиционных параметрах.

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

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

Примечание

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

class inspect.Signature(parameters=None, *, return_annotation=Signature.empty)¶

Объект Signature представляет сигнатуру вызова функции и её аннотацию возвращаемого значения. Для каждого параметра, принимаемого функцией, он сохраняет объект Parameter в своей коллекции parameters.

Необязательный аргумент parameters – это последовательность объектов Parameter, которая проверяется на отсутствие дублирующихся имён параметров и на правильный порядок: сначала только позиционные, затем позиционно-ключевые, а параметры со значениями по умолчанию следуют за параметрами без них.

Необязательный аргумент return_annotation может быть произвольным объектом Python и является аннотацией возвращаемого значения вызываемого объекта.

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

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

empty¶

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

parameters¶

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

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

return_annotation¶

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

bind(*args, **kwargs)¶

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

bind_partial(*args, **kwargs)¶

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

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

Создаёт новый экземпляр Signature на основе экземпляра, для которого был вызван replace. Можно передать другие parameters и/или return_annotation, чтобы переопределить соответствующие свойства базовой сигнатуры. Чтобы удалить return_annotation из скопированной сигнатуры, укажите Signature.empty.

>>> def test(a, b):
...     pass
>>> sig = signature(test)
>>> new_sig = sig.replace(return_annotation="new return anno")
>>> str(new_sig)
"(a, b) -> 'new return anno'"

classmethod from_callable(obj, *, follow_wrapped=True, globalns=None, localns=None)¶

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

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

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

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

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

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

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

Изменено в версии 3.5: Объекты Parameter стали сериализуемыми (с помощью pickle) и хешируемыми.

empty¶

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

name¶

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

Особенности реализации CPython: CPython генерирует неявные имена параметров вида .0 в объектах кода, используемых для реализации включений (comprehensions) и выражений-генераторов.

Изменено в версии 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()) # Создаст поверхностную копию '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)

Классы и функции¶Classes and functions

inspect.getclasstree(classes, unique=False)¶

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

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

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

Примечание

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

inspect.getmro(cls)¶

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

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

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

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

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

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

inspect.getclosurevars(func)¶

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

TypeError возбуждается, если func не является функцией или методом Python.

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

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

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

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

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

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

inspect.get_annotations(obj, *, globals=None, locals=None, eval_str=False)¶

Вычисляет словарь аннотаций для объекта.

obj может быть вызываемым объектом, классом или модулем. Передача объекта любого другого типа вызывает TypeError.

Возвращает словарь. get_annotations() каждый раз возвращает новый словарь; два его вызова для одного и того же объекта вернут два разных, но эквивалентных словаря.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Стек интерпретатора¶The interpreter stack

Когда следующие функции возвращают «записи о фреймах», каждая запись представляет собой именованный кортеж FrameInfo(frame, filename, lineno, function, code_context, index). Кортеж содержит объект фрейма, имя файла, номер текущей строки, имя функции, список строк контекста из исходного кода и индекс текущей строки в этом списке.

def handle_stackframe_without_leak():
    frame = inspect.currentframe()
    try:
        # Выполнить действие с фреймом
    finally:
        del frame

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

inspect.getframeinfo(frame, context=1)¶

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

inspect.getouterframes(frame, context=1)¶

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

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

inspect.getinnerframes(traceback, context=1)¶

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

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

inspect.currentframe()¶

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

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

inspect.stack(context=1)¶

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

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

inspect.trace(context=1)¶

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

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

Статическое получение атрибутов¶Fetching attributes statically

И 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-дескрипторов их вызов может запустить выполнение кода:

# Пример кода для разрешения встроенных типов дескрипторов
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:
        # Дескрипторы могут вызывать AttributeError, чтобы
        # указать, что нет нижележащего значения
        # в этом случае сам дескриптор будет
        # придется сделать
        pass

Текущее состояние генераторов и корутин¶Current State of Generators and Coroutines

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

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

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

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

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

inspect.getcoroutinelocals(coroutine)¶

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

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

Битовые флаги объектов кода¶Code Objects Bit Flags

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

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

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

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

--details¶

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