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

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

Этот модуль предоставляет четыре основных вида услуг: проверка типов, получение исходного кода, проверка классов и функций и проверка стека интерпретатора.

Типы и члены

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

Тип Атрибут Описание
module __doc__ строка документации
  __file__ имя файла (отсутствует для встроенных модулей)
class __doc__ строка документации
  __name__ имя, с которым был определён этот класс
  __qualname__ составное имя
  __module__ имя модуля, в котором был определён этот класс
method __doc__ строка документации
  __name__ имя, с помощью которого был определён этот метод
  __qualname__ составное имя
  __func__ объект функции, содержащий реализацию метода
  __self__ сущность, с которой связан этот метод или None
  __module__ имя модуля, в котором был определён этот метод
function __doc__ строка документации
  __name__ имя, с которым была определена функция
  __qualname__ составное имя
  __code__ кодовый объект, содержащий скомпилированную функцию байт-кода
  __defaults__ кортеж любого значения по умолчанию для позиционных или ключевых параметров
  __kwdefaults__ отображение любого значения по умолчанию для только ключевых параметров
  __globals__ глобальное пространство имён, в котором была определена функция
  __annotations__ отображение имён параметров в аннотации; "return" ключ зарезервирован для возвращаемой аннотации.
  __module__ имя модуля, в котором была определена функция
traceback tb_frame объект фрейм на этом уровне
  tb_lasti индекс последней попытки выполнения инструкции в байт-коде
  tb_lineno текущий номер строки в исходном Python коде
  tb_next следующий внутренний объект трейсбэка (вызывается этим уровнем)
frame f_back следующий объект внешнего фрейма (вызывающий объект этого фрейма)
  f_builtins встроенное пространство имён, видимое этим фреймом
  f_code объект кода выполняемый в этом фрейме
  f_globals глобальное пространство имён, видимое этим фрейме
  f_lasti индекс последней попытки выполнения команды в байт-коде
  f_lineno текущий номер строки в исходном Python коде
  f_locals локальное пространство имён, видимое этим фреймом
  f_trace отслеживание функции для этого фрейма или None
code co_argcount количество аргументов (не включая только ключевые аргументы, * или ** args)
  co_code строка исходного скомпилированного байт-кода
  co_cellvars кортеж имён переменных ячейки (на который ссылается области видимости)
  co_consts кортеж констант используемый в байт-коде
  co_filename имя файла, в котором был создан этот объект кода
  co_firstlineno номер первой строки в исходном Python коде
  co_flags битовая карта флагов CO_*, подробнее здесь
  co_lnotab кодированный отображение номеров строк на индексы байт-кода
  co_freevars кортеж имён свободных переменных (на которые ссылается замыкание функции)
  co_posonlyargcount количество только позиционных аргументов
  co_kwonlyargcount число только ключевых аргументов (не включая** arg)
  co_name имя, с которым был определён этот объект кода
  co_names кортеж имён локальных переменных
  co_nlocals число локальных переменных
  co_stacksize требуемое пространство стека виртуальной машины
  co_varnames кортеж имён аргументов и локальных переменных
generator __name__ имя
  __qualname__ составное имя
  gi_frame фрейм
  gi_running работает ли генератор?
  gi_code код
  gi_yieldfrom объект, итерируемый yield from или None
coroutine __name__ имя
  __qualname__ составное имя
  cr_await ожидаемый объект или None
  cr_frame фрейм
  cr_running работает ли корутина?
  cr_code код
  cr_origin где был создана корутина или None. См. sys.set_coroutine_origin_tracking_depth()
builtin __doc__ строка документации
  __name__ исходное имя этой функции или метода
  __qualname__ составное имя
  __self__ сущность, с которым связан метод или None

Изменено в версии 3.5: Добавлены к генераторам атрибуты __qualname__ и gi_yieldfrom.

Атрибут генераторов __name__ теперь устанавливается по имени функции, а не по имени кода, и теперь его можно изменить.

Изменено в версии 3.7: К корутинам добавлен атрибут cr_origin.

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

inspect.isgeneratorfunction(object)

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

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

inspect.isgenerator(object)

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

inspect.iscoroutinefunction(object)

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

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

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

inspect.iscoroutine(object)

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

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

inspect.isawaitable(object)

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

Также может использоваться для отличия корутин на основе генераторов от обычных генераторов:

def gen():
    yield
@types.coroutine
def gen_coro():
    yield

assert not isawaitable(gen())
assert isawaitable(gen_coro())

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

inspect.isasyncgenfunction(object)

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

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

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

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

inspect.isasyncgen(object)

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

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

inspect.istraceback(object)

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

inspect.isframe(object)

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

inspect.iscode(object)

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

inspect.isbuiltin(object)

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

inspect.isroutine(object)

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

inspect.isabstract(object)

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

inspect.ismethoddescriptor(object)

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

Это, например, верно для int.__add__. У объекта, прошедшего этот тест, есть метод __get__(), но нет метода __set__(), но помимо этого множество атрибутов меняется. Атрибут __name__ обычно имеет смысл, а __doc__ — часто.

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

inspect.isdatadescriptor(object)

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

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

inspect.isgetsetdescriptor(object)

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

Детали реализации CPython: 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: OSError возникает вместо IOError, теперь это псевдоним первого.

inspect.getsource(object)

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

Изменено в версии 3.3: OSError возникает вместо IOError, теперь это псевдоним прежнего.

inspect.cleandoc(doc)

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

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

Анализ вызываемых объектов с помощью объекта Signature

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

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

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

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

empty

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

parameters

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

Изменено в версии 3.7: Начиная с версии 3.7 Python явно гарантировал, что он сохраняет порядок объявления только ключевые параметров, хотя на практике этот порядок всегда сохранялся в 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 на основе экземпляра, для которого была вызвана замена. Можно передать разные 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.replace() для создания измененной копии.

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

empty

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

name

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

Детали реализации CPython: CPython генерирует неявные имена параметров вида .0 для объектов кода, используемых для реализации представлений и выражений генератора.

Изменено в версии 3.6: Имена параметров отображаются этим модулем как имена, например implicit0.

default

Значение по умолчанию для параметра. Если параметр не имеет значения по умолчанию, этому атрибуту присваивается значение Parameter.empty.

annotation

Аннотация для параметра. Если параметр не имеет аннотации, для этого атрибута устанавливается значение Parameter.empty.

kind

Определяет, как значения аргументов привязаны к параметру. Возможные значения (доступны через Parameter, например Parameter.KEYWORD_ONLY):

Имя Смысл
POSITIONAL_ONLY Значение должно быть указано как позиционный аргумент. Позиционными являются только те параметры, которые появляются перед записью / (если она присутствует) в определении функции Python.
POSITIONAL_OR_KEYWORD Значение может быть представлено в виде ключевого или позиционного аргумента (это стандартное поведение биндинга для функций, реализованных в Python.)
VAR_POSITIONAL Кортеж позиционных аргументов, не связанных ни с одним другим параметром. Это соответствует параметру *args в определении функции Python.
KEYWORD_ONLY Значение должно быть указано в качестве ключевого аргумента. Только ключевых параметры — это параметры, которые появляются после записи * или *args в определении функции Python.
VAR_KEYWORD Словарь ключевых аргументов, которые не привязаны к какому-либо другому параметру. Это соответствует параметру **kwargs в определении функции Python.

Пример: распечатать все только ключевые аргументы, без значений по умолчанию:

>>> def foo(a, b, *, c, d=10):
...     pass

>>> sig = signature(foo)
>>> for param in sig.parameters.values():
...     if (param.kind == param.KEYWORD_ONLY and
...                        param.default is param.empty):
...         print('Parameter:', param)
Parameter: c
kind.description

Определяет значение перечисления Parameter.kind.

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

Пример: распечатать все описания аргументов:

>>> def foo(a, b, *, c, d=10):
...     pass

>>> sig = signature(foo)
>>> for param in sig.parameters.values():
...     print(param.kind.description)
positional or keyword
positional or keyword
keyword-only
keyword-only
replace(*[, name][, kind][, default][, annotation])

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

>>> from inspect import Parameter
>>> param = Parameter('foo', Parameter.KEYWORD_ONLY, default=42)
>>> str(param)
'foo=42'

>>> str(param.replace()) # Создаст неглубокую копию '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)

См.также

PEP 362 — Функции объекта Signature.
Подробная спецификация, детали реализации и примеры.

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

inspect.getclasstree(classes, unique=False)

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

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) к связанному экземпляру. Возвращается dict, отображающий имена аргументов (включая имена аргументов * и **, если есть) с их значениями из 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). Кортеж содержит объект фрейма, имя файла, номер строки текущей строки, имя функции, список строк контекста из исходного кода и индекс текущей строки в этом списке.

Изменено в версии 3.5: Возвращает именованный кортеж вместо кортежа.

Примечание

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

Хотя детектор циклов поймает их, уничтожение фреймов (и локальных переменных) можно сделать детерминированным, удалив цикл в предложении finally. Это также важно, если детектор циклов был отключён при компиляции Python или использовании gc.disable(). Например:

def handle_stackframe_without_leak():
    frame = inspect.currentframe()
    try:
        # сделать что-нибудь с фреймом
    finally:
        del frame

Если вы хотите сохранить фрейм (например, чтобы распечатать трассировку позже), вы также можете разорвать ссылочные циклы, используя метод frame.clear().

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

inspect.getframeinfo(frame, context=1)

Получить информацию о фрейме или объекте трассировки. Возвращается именованный кортеж 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)

Получить список записей фреймов для фрейма трассировки и всех внутренних фреймов. Данные фреймы представляют вызовы, сделанные как следствие 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).

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

И 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

Текущее состояние генераторов и корутин

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

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

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

inspect.CO_OPTIMIZED

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

inspect.CO_NEWLOCALS

Если установлено, новый dict будет создан для 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.

Примечание

Флаги специфичны для CPython и не могут быть определены в других реализациях Python. Кроме того, флаги являются деталью реализации и могут быть удалены или объявлены устаревшими в будущих выпусках Python. Рекомендуется использовать общедоступные API из модуля inspect для любых нужд самоанализа.

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

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

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

--details

Распечатать информацию об указанном объекте, а не исходном коде.