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

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

---

Модуль 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() now возвращает 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() имеют значение true.

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

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

inspect.isdatadescriptor(object)

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

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

inspect.isgetsetdescriptor(object)

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

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

inspect.ismemberdescriptor(object)

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

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

Восстановление исходного кода

inspect.getdoc(object)

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

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

inspect.getcomments(object)

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

inspect.getfile(object)

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

inspect.getmodule(object)

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

inspect.getsourcefile(object)

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

inspect.getsourcelines(object)

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

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

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

Изменено в версии 3.5: Объекты Signature являются picklable и хэшируемыми.

empty

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

parameters

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

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

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

class inspect.BoundArguments

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

arguments

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

Should be used in conjunction with Signature.parameters for any argument processing purposes.

Примечание

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

args

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

kwargs

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

signature

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

apply_defaults()

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

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

Для аргументов variable-ключевой (**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-кортеж, содержащий класс и кортеж его базовых классов. Если аргумент уникальный имеет значение true, в структуре возвращенный для каждого класса в данном списке отображается ровно одна запись. В противном случае классы, использующие несколько наследований и их потомки, появятся несколько раз.

inspect.getargspec(func)

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

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

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

inspect.getfullargspec(func)

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

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

args - список имен позиционных параметров. varargs - имя параметра * или None, если произвольные позиционные аргументы не принимаются. varkw - имя параметра ** или None, если произвольные аргументы ключевой не принимаются. defaults является n-tuple аргумента по умолчанию значения, соответствующего последним n позиционным параметрам, или None, если такие значения по умолчанию не определены. kwonlyargs - список имен параметров ключевой-only в порядке объявления. 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 только явно гарантировал, что он сохранил порядок объявления параметров ключевой-only по версии 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]])

Форматировать довольно аргумент spec из значения возвращенный по 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() и Сигнатуру объекта, которые обеспечивают лучший интерфейс API для поиска вызовов.

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

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

Примечание

Эта функция была случайно помечена как устаревшая в 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 к модулю функции globals и builtins к 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’s включен. Если такие циклы должны создаваться, важно обеспечить их явный разрыв, чтобы избежать задержки разрушения объектов и увеличения потребления памяти.

Хотя датчик цикла поймает их, разрушение структур (и переменные локальная) может быть сделано детерминированным, удалив цикл в 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 не может (как атрибуты, которые вызывают Attrib дескрипторы Error). Это может также объекты возвращает дескрипторы вместо членов сущность.

Если сущность __dict__ затеняется другим членом (например, свойством), то эта функция не сможет найти элементы сущность.

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

getattr_static() не разрешает дескрипторы, например slot дескрипторы или 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: В настоящее время приостановлено в выражении 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.

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

Объекты Python код имеют co_flags атрибут, являющийся растровым изображением следующих флагов:

inspect.CO_OPTIMIZED

Объект код оптимизирован, с помощью быстрых локальных.

inspect.CO_NEWLOCALS

Если установлено, новый словарь будет создан для f_locals структуры, когда объект код будет выполнен.

inspect.CO_VARARGS

Объект код имеет переменный позиционный параметр (*args-подобный).

inspect.CO_VARKEYWORDS

Объект код имеет переменный параметр ключевой (**kwargs-like).

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. Рекомендуется использовать public API из модуля inspect для любых потребностей в самоанализе.

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

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

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

--details

Информация о печати об указанном объекте, а не источнике код