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

Типы и члены¶

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

inspect.getmembers(object[, predicate])¶

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

Примечание

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

inspect.getmembers_static(object[, predicate])¶

Возвращает все элементы объекта в списке пар (name, value), отсортированных по имени, без запуска динамического поиска по протоколу дескриптора, __getattr__ или __getattribute__. Необязательно возвращать только те элементы, которые удовлетворяют заданному предикату.

Примечание

getmembers_static() возможно, не удастся получить все элементы, которые могут быть получены get members (например, динамически создаваемые атрибуты), и могут быть найдены элементы, которые не могут быть получены getmembers (например, дескрипторы, которые вызывают AttributeError). В некоторых случаях он также может возвращать объекты-дескрипторы вместо элементов экземпляра.

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

inspect.getmodulename(path)¶

Возвращает имя модуля, указанное в файле path, без указания имен входящих в него пакетов. Расширение файла проверяется на соответствие всем записям в importlib.machinery.all_suffixes(). Если оно совпадает, возвращается конечный компонент path с удаленным расширением. В противном случае возвращается 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)¶

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

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

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

inspect.iscoroutine(object)¶

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

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

inspect.isawaitable(object)¶

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

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

import types

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

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

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

inspect.isasyncgenfunction(object)¶

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

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

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

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

inspect.isasyncgen(object)¶

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

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

inspect.istraceback(object)¶

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

inspect.isframe(object)¶

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

inspect.iscode(object)¶

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

inspect.isbuiltin(object)¶

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

inspect.ismethodwrapper(object)¶

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

Это экземпляры MethodWrapperType, такие как __str__(), __eq__() и __repr__().

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

inspect.isroutine(object)¶

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

inspect.isabstract(object)¶

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

inspect.ismethoddescriptor(object)¶

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

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

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

inspect.isdatadescriptor(object)¶

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

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

inspect.isgetsetdescriptor(object)¶

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

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

inspect.ismemberdescriptor(object)¶

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

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

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

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)¶

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

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

inspect.getsource(object)¶

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

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

inspect.cleandoc(doc)¶

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

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

Самоанализ, вызываемый с помощью объекта Signature¶

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

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

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

>>> 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() будет предпринята попытка автоматической разбивки аннотаций на строки с помощью get_annotations(). Параметры globals, locals и eval_str передаются в get_annotations() при разрешении аннотаций; инструкции по использованию этих параметров приведены в документации для get_annotations().

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

Косая черта(/) в сигнатуре функции означает, что предшествующие ей параметры являются позиционными. Для получения дополнительной информации см. the FAQ entry on positional-only parameters.

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

Изменено в версии 3.10: Были добавлены параметры globals, locals и eval_str.

Примечание

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

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

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

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

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

Необязательный аргумент return_annotation может быть произвольным объектом Python. Он представляет собой аннотацию «return» вызываемого объекта.

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

Изменено в версии 3.5: Signature объекты теперь доступны для выбора и hashable.

empty¶

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

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(). Можно передать другие параметры и/или 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, globals=None, locals=None, eval_str=False)¶

Возвращает объект Signature (или его подкласс) для данного вызываемого объекта obj.

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

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

В остальном его поведение идентично поведению signature().

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

Изменено в версии 3.10: Были добавлены параметры globals, locals и eval_str.

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

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

Изменено в версии 3.5: Объекты параметров теперь доступны для выбора и имеют значение hashable.

empty¶

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

name¶

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

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

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

default¶

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

annotation¶

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

kind¶

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

Имя	Значение
ТОЛЬКО ПОЗИЦИОННЫЙ	Значение должно быть указано в качестве позиционного аргумента. Только позиционные параметры - это те, которые отображаются перед записью / (если она присутствует) в определении функции Python.
ПОЗИЦИОННОЕ ИЛИ КЛЮЧЕВОЕ СЛОВО	Значение может быть задано либо в виде ключевого слова, либо в виде позиционного аргумента (это стандартное поведение привязки для функций, реализованных в Python).
ПЕРЕМЕННЫЙ_ПОЗИЦИОННЫЙ	Набор позиционных аргументов, которые не привязаны ни к какому другому параметру. Это соответствует параметру *args в определении функции Python.
ТОЛЬКО КЛЮЧЕВОЕ СЛОВО_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()) # Will create a shallow copy of 'param'
'foo=42'

>>> str(param.replace(default=Parameter.empty, annotation='spam'))
"foo: 'spam'"

Изменено в версии 3.4: В Python 3.3 для объектов Parameter было разрешено устанавливать значение name в None, если для их kind было установлено значение POSITIONAL_ONLY. Это больше не разрешено.

class inspect.BoundArguments¶

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

arguments¶

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

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

Примечание

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

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

args¶

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

kwargs¶

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

signature¶

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

apply_defaults()¶

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

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

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

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

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

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

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

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

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

inspect.getclasstree(classes, unique=False)¶

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

inspect.getfullargspec(func)¶

Возвращает имена и значения по умолчанию параметров функции Python. Возвращается значение named tuple:

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

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

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

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

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

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

inspect.getargvalues(frame)¶

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

Примечание

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

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

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

Примечание

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

inspect.getmro(cls)¶

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

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

Привяжите args и kwd к именам аргументов функции или метода 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 их текущим значениям. Возвращается значение A named tuple ClosureVars(nonlocals, globals, builtins, unbound). нелокальные сопоставляют имена, на которые ссылаются, с лексическими переменными замыкания, глобальные с глобальными параметрами модуля функции и встроенные элементы со встроенными элементами, видимыми из тела функции. несвязанный - это набор имен, на которые ссылается функция, которые вообще не могут быть разрешены с учетом текущих глобальных параметров модуля и встроенных функций.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

• Если значение eval_str равно true, то 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 является наилучшей практикой для доступа к аннотациям любого объекта. Смотрите Аннотации к лучшим практикам для получения дополнительной информации о рекомендациях по аннотациям.

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

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

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

class inspect.FrameInfo¶

frame¶

frame object, которому соответствует запись.

filename¶

Имя файла, связанное с кодом, выполняемым фреймом, которому соответствует эта запись.

lineno¶

Номер строки текущей строки, связанной с кодом, выполняемым фреймом, которому соответствует эта запись.

function¶

Имя функции, выполняемой фреймом, которому соответствует эта запись.

code_context¶

Список строк контекста из исходного кода, который выполняется фреймом, соответствующему этой записи.

index¶

Индекс текущей выполняемой строки в списке code_context.

positions¶

Объект dis.Positions, содержащий номер начальной строки, номер конечной строки, смещение начального столбца и смещение конечного столбца, связанные с командой, выполняемой фреймом, которому соответствует эта запись.

Изменено в версии 3.5: Верните named tuple вместо tuple.

Изменено в версии 3.11: FrameInfo теперь является экземпляром класса (который обратно совместим с предыдущим named tuple).

class inspect.Traceback¶

filename¶

Имя файла, связанного с кодом, выполняемым фреймом, которому соответствует эта обратная трассировка.

lineno¶

Номер строки текущей строки, связанной с кодом, выполняемым фреймом, которому соответствует эта обратная трассировка.

function¶

Имя функции, выполняемой фреймом, которому соответствует эта обратная трассировка.

code_context¶

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

index¶

Индекс текущей выполняемой строки в списке code_context.

positions¶

Объект dis.Positions, содержащий номер начальной строки, номер конечной строки, смещение начального столбца и смещение конечного столбца, связанный с командой, выполняемой фреймом, которому соответствует эта обратная трассировка.

Изменено в версии 3.11: Traceback теперь является экземпляром класса (который обратно совместим с предыдущим named tuple).

def handle_stackframe_without_leak():
    frame = inspect.currentframe()
    try:
        # do something with the frame
    finally:
        del frame

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

inspect.getframeinfo(frame, context=1)¶

Получает информацию о фрейме или объекте обратной трассировки. Возвращается объект Traceback.

Изменено в версии 3.11: Вместо именованного кортежа возвращается объект Traceback.

inspect.getouterframes(frame, context=1)¶

Получаем список объектов FrameInfo для фрейма и всех внешних фреймов. Эти фреймы представляют вызовы, которые приводят к созданию frame. Первая запись в возвращаемом списке представляет frame; последняя запись представляет самый внешний вызов в стеке frame.

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

Изменено в версии 3.11: Возвращается список объектов FrameInfo.

inspect.getinnerframes(traceback, context=1)¶

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

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

Изменено в версии 3.11: Возвращается список объектов FrameInfo.

inspect.currentframe()¶

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

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

inspect.stack(context=1)¶

Возвращает список объектов FrameInfo для стека вызывающей стороны. Первая запись в возвращаемом списке представляет вызывающую сторону; последняя запись представляет самый внешний вызов в стеке.

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

Изменено в версии 3.11: Возвращается список объектов FrameInfo.

inspect.trace(context=1)¶

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

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

Изменено в версии 3.11: Возвращается список объектов FrameInfo.

Статическая выборка атрибутов¶

И getattr(), и hasattr() могут инициировать выполнение кода при выборке или проверке наличия атрибутов. Будут вызываться дескрипторы, такие как свойства, и могут быть вызваны __getattr__() и __getattribute__().

В случаях, когда требуется пассивный самоанализ, например, в инструментах документирования, это может быть неудобно. getattr_static() имеет ту же сигнатуру, что и getattr(), но позволяет избежать выполнения кода при извлечении атрибутов.

inspect.getattr_static(obj, attr, default=None)¶

Извлекать атрибуты без запуска динамического поиска по протоколу дескриптора, __getattr__() или __getattribute__().

Примечание: возможно, эта функция не сможет получить все атрибуты, которые может получить getattr (например, динамически создаваемые атрибуты), и может найти атрибуты, которые не может получить getattr (например, дескрипторы, которые вызывают AttributeError). Она также может возвращать объекты-дескрипторы вместо элементов экземпляра.

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

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

getattr_static() не разрешает дескрипторы, например, дескрипторы слотов или дескрипторы get set для объектов, реализованных на C. Вместо базового атрибута возвращается объект-дескриптор.

Вы можете обработать это с помощью кода, подобного приведенному ниже. Обратите внимание, что для произвольных дескрипторов get set их вызов может вызвать выполнение кода:

# example code for resolving the builtin descriptor types
class _foo:
    __slots__ = ['foo']

slot_descriptor = type(_foo.foo)
getset_descriptor = type(type(open(__file__)).name)
wrapper_descriptor = type(str.__dict__['__add__'])
descriptor_types = (slot_descriptor, getset_descriptor, wrapper_descriptor)

result = getattr_static(some_object, 'foo')
if type(result) in descriptor_types:
    try:
        result = result.__get__()
    except AttributeError:
        # descriptors can raise AttributeError to
        # indicate there is no underlying value
        # in which case the descriptor itself will
        # have to do
        pass

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

При реализации планировщиков сопрограмм и для других расширенных применений генераторов полезно определить, выполняется ли генератор в данный момент, ожидает ли запуска, возобновления выполнения или уже завершено выполнение. getgeneratorstate() позволяет легко определить текущее состояние генератора.

inspect.getgeneratorstate(generator)¶

Получите текущее состояние генератора-итератора.

Возможными состояниями являются:

• GEN_CREATED: Ожидание начала выполнения.

• GEN_RUNNING: В данный момент выполняется интерпретатором.

• GEN_SUSPENDED: В настоящее время приостановлено по выражению yield.

• GEN_CLOSED: Выполнение завершено.

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

inspect.getcoroutinestate(coroutine)¶

Получает текущее состояние объекта сопрограммы. Функция предназначена для использования с объектами сопрограммы, созданными функциями async def, но будет принимать любые объекты, подобные сопрограмме, которые имеют атрибуты cr_running и cr_frame.

Возможными состояниями являются:

• CORO_CREATED: Ожидает начала выполнения.

• CORO_RUNNING: В данный момент выполняется интерпретатором.

• CORO_SUSPENDED: В данный момент приостановлено из-за выражения ожидания.

• CORO_CLOSED: Выполнение завершено.

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

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

inspect.getgeneratorlocals(generator)¶

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

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

inspect.CO_VARARGS¶

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

inspect.CO_VARKEYWORDS¶

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

inspect.CO_NESTED¶

Флаг устанавливается, когда объект кода является вложенной функцией.

inspect.CO_GENERATOR¶

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

inspect.CO_COROUTINE¶

Флаг устанавливается, если объект кода является функцией сопрограммы. Когда объект кода выполняется, он возвращает объект сопрограммы. Более подробную информацию смотрите в разделе PEP 492.

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

inspect.CO_ITERABLE_COROUTINE¶

Флаг используется для преобразования генераторов в основанные на генераторах сопрограммы. Объекты-генераторы с этим флагом могут использоваться в выражении await и могут быть объектами сопрограммы yield from. Более подробную информацию смотрите в разделе PEP 492.

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

inspect.CO_ASYNC_GENERATOR¶

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

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

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

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

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

--details¶

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