inspect
— Осмотреть живые объекты¶
Источник: Lib/inspect.py
Модуль inspect
предоставляет несколько полезных функций для получения информации о живых объектах, таких как модули, классы, методы, функции, трассировки, объекты фреймов и объекты кода. Например, с его помощью можно изучить содержимое класса, получить исходный код метода, извлечь и отформатировать список аргументов функции или получить всю информацию, необходимую для отображения подробной обратной трассировки.
Существует четыре основных вида услуг, предоставляемых этим модулем: проверка типов, получение исходного кода, проверка классов и функций, а также проверка стека интерпретатора.
Типы и члены¶
Функция getmembers()
извлекает члены объекта, такого как класс или модуль. Функции, имена которых начинаются с «is», в основном предоставляются в качестве удобного выбора второго аргумента для getmembers()
. Они также помогают определить, когда вы можете ожидать найти следующие специальные атрибуты (см. Атрибуты модуля, связанные с импортом для атрибутов модуля):
Тип |
Атрибут |
Описание |
---|---|---|
класс |
__doc__ |
строка документации |
__name__ |
имя, под которым был определен этот класс |
|
__qualname__ |
квалифицированное имя |
|
__модуль__ |
имя модуля, в котором был определен этот класс |
|
__type_params__ |
Кортеж, содержащий type parameters общего класса |
|
метод |
__doc__ |
строка документации |
__name__ |
имя, под которым был определен этот метод |
|
__qualname__ |
квалифицированное имя |
|
__func__ |
объект функции, содержащий реализацию метода |
|
__self__ |
экземпляр, к которому привязан этот метод, или |
|
__модуль__ |
имя модуля, в котором был определен этот метод |
|
функция |
__doc__ |
строка документации |
__name__ |
имя, под которым была определена эта функция |
|
__qualname__ |
квалифицированное имя |
|
__код__ |
объект кода, содержащий скомпилированную функцию bytecode |
|
__defaults__ |
кортеж любых значений по умолчанию для позиционных или ключевых параметров |
|
__kwdefaults__ |
отображение любых значений по умолчанию для параметров, относящихся только к ключевым словам |
|
__globals__ |
глобальное пространство имен, в котором была определена эта функция |
|
__builtins__ |
пространство имен builtins |
|
__аннотации__ |
сопоставление имен параметров с аннотациями; ключ |
|
__type_params__ |
Кортеж, содержащий type parameters общей функции |
|
__модуль__ |
имя модуля, в котором была определена эта функция |
|
traceback |
tb_frame |
объект кадра на этом уровне |
tb_lasti |
индекс последней попытки выполнения инструкции в байткоде |
|
tb_lineno |
номер текущей строки в исходном коде Python |
|
tb_next |
следующий внутренний объект трассировки (вызываемый на этом уровне) |
|
рама |
f_back |
следующий объект внешнего кадра (вызывающий этот кадр) |
f_builtins |
пространство имен builtins, видимое этим кадром |
|
f_code |
объект кода, выполняемый в этом кадре |
|
f_globals |
глобальное пространство имен, видимое этим кадром |
|
f_lasti |
индекс последней попытки выполнения инструкции в байткоде |
|
f_lineno |
номер текущей строки в исходном коде Python |
|
f_locals |
локальное пространство имен, видимое этим кадром |
|
f_trace |
функция трассировки для этого кадра, или |
|
код |
co_argcount |
количество аргументов (не включая аргументы, содержащие только ключевые слова, * или ** аргументы) |
код |
строка необработанного скомпилированного байткода |
|
co_cellvars |
кортеж имен переменных ячеек (на которые ссылаются содержащие диапазоны) |
|
co_consts |
кортеж констант, используемых в байткоде |
|
co_filename |
имя файла, в котором был создан этот объект кода |
|
co_firstlineno |
номер первой строки в исходном коде Python |
|
co_flags |
растровое изображение |
|
co_lnotab |
кодированное отображение номеров строк на индексы байткода |
|
co_freevars |
кортеж имен свободных переменных (на которые можно ссылаться через закрытие функции) |
|
co_posonlyargcount |
количество только позиционных аргументов |
|
co_kwonlyargcount |
количество аргументов, содержащих только ключевые слова (не включая ** arg) |
|
совместное имя |
имя, под которым был определен данный объект кода |
|
co_qualname |
полное имя, с которым был определен этот объект кода |
|
совместные имена |
кортеж имен, отличных от аргументов и локалей функции |
|
co_nlocals |
количество локальных переменных |
|
co_stacksize |
Необходимое место в стеке виртуальной машины |
|
co_varnames |
кортеж имен аргументов и локальных переменных |
|
генератор |
__name__ |
имя |
__qualname__ |
квалифицированное имя |
|
gi_frame |
рама |
|
gi_running |
Генератор работает? |
|
gi_code |
код |
|
gi_yieldfrom |
объект, итерируемый по |
|
coroutine |
__name__ |
имя |
__qualname__ |
квалифицированное имя |
|
cr_await |
объект, которого ожидают, или |
|
cr_frame |
рама |
|
cr_running |
выполняется ли корутина? |
|
cr_code |
код |
|
cr_origin |
где была создана coroutine, или |
|
встроенный |
__doc__ |
строка документации |
__name__ |
оригинальное имя этой функции или метода |
|
__qualname__ |
квалифицированное имя |
|
__self__ |
экземпляр, к которому привязан метод, или |
Изменено в версии 3.5: Добавьте атрибуты __qualname__
и gi_yieldfrom
к генераторам.
Атрибут __name__
генераторов теперь устанавливается из имени функции, а не из имени кода, и теперь его можно изменить.
Изменено в версии 3.7: Добавьте атрибут cr_origin
к корутинам.
Изменено в версии 3.10: Добавьте атрибут __builtins__
в функции.
- inspect.getmembers(object[, predicate])¶
Возвращает все члены объекта в виде списка пар
(name, value)
, отсортированных по имени. Если указан необязательный аргумент predicate, который будет вызван с объектомvalue
каждого члена, то будут включены только те члены, для которых предикат возвращает истинное значение.Примечание
getmembers()
будет возвращать атрибуты класса, определенные в метаклассе, только если аргумент является классом и эти атрибуты были перечислены в пользовательском__dir__()
метакласса.
- inspect.getmembers_static(object[, predicate])¶
Возвращает все члены объекта в виде списка пар
(name, value)
, отсортированных по имени, не вызывая динамического поиска по протоколу дескрипторов, __getattr__ или __getattribute__. Опционально можно возвращать только те члены, которые удовлетворяют заданному предикату.Примечание
getmembers_static()
может не получить все члены, которые может получить getmembers (например, динамически создаваемые атрибуты), и может найти члены, которые getmembers не может получить (например, дескрипторы, вызывающие ошибку AttributeError). В некоторых случаях она может возвращать объекты дескрипторов вместо членов экземпляра.Added in version 3.11.
- inspect.getmodulename(path)¶
Возвращает имя модуля, названного по файлу path, без учета имен вложенных пакетов. Расширение файла проверяется на соответствие всем записям в
importlib.machinery.all_suffixes()
. Если оно совпадает, возвращается последний компонент пути с удаленным расширением. В противном случае возвращаетсяNone
.Обратите внимание, что эта функция только возвращает осмысленное имя для реальных модулей Python - пути, которые потенциально могут ссылаться на пакеты Python, все равно вернут
None
.Изменено в версии 3.3: Функция основана непосредственно на
importlib
.
- inspect.ismodule(object)¶
Возвращает
True
, если объект является модулем.
- inspect.isclass(object)¶
Возвращает
True
, если объект является классом, встроенным или созданным в коде Python.
- inspect.ismethod(object)¶
Возвращает
True
, если объект является связанным методом, написанным на языке Python.
- inspect.isfunction(object)¶
Возвращает
True
, если объект является функцией Python, которая включает функции, созданные выражением lambda.
- inspect.isgeneratorfunction(object)¶
Возвращает
True
, если объект является генераторной функцией Python.Изменено в версии 3.8: Функции, обернутые в
functools.partial()
, теперь возвращаютTrue
, если обернутая функция является генераторной функцией Python.Изменено в версии 3.13: Функции, обернутые в
functools.partialmethod()
, теперь возвращаютTrue
, если обернутая функция является генераторной функцией Python.
- inspect.isgenerator(object)¶
Возвращает
True
, если объект является генератором.
- inspect.iscoroutinefunction(object)¶
Возвращает
True
, если объект является coroutine function (функцией, определенной с помощью синтаксисаasync def
),functools.partial()
, обертывающей coroutine function, или функцией синхронизации, отмеченнойmarkcoroutinefunction()
.Added in version 3.5.
Изменено в версии 3.8: Функции, обернутые в
functools.partial()
, теперь возвращаютTrue
, если обернутая функция является coroutine function.Изменено в версии 3.12: Функции синхронизации, отмеченные символом
markcoroutinefunction()
, теперь возвращаютTrue
.Изменено в версии 3.13: Функции, обернутые в
functools.partialmethod()
, теперь возвращаютTrue
, если обернутая функция является coroutine function.
- inspect.markcoroutinefunction(func)¶
Декоратор для обозначения вызываемого объекта как coroutine function, если в противном случае он не будет обнаружен
iscoroutinefunction()
.Это может быть полезно для функций синхронизации, возвращающих coroutine, если функция передается в API, требующий
iscoroutinefunction()
.Если возможно, предпочтительнее использовать функцию
async def
. Также допустимо вызвать функцию и проверить возврат с помощьюiscoroutine()
.Added in version 3.12.
- inspect.iscoroutine(object)¶
Возвращает
True
, если объект является coroutine, созданным функциейasync def
.Added in version 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())
Added in version 3.5.
- inspect.isasyncgenfunction(object)¶
Возвращает
True
, если объект является функцией asynchronous generator, например:>>> async def agen(): ... yield 1 ... >>> inspect.isasyncgenfunction(agen) True
Added in version 3.6.
Изменено в версии 3.8: Функции, обернутые в
functools.partial()
, теперь возвращаютTrue
, если обернутая функция является функцией asynchronous generator.Изменено в версии 3.13: Функции, обернутые в
functools.partialmethod()
, теперь возвращаютTrue
, если обернутая функция является coroutine function.
- inspect.isasyncgen(object)¶
Возвращает
True
, если объект является asynchronous generator iterator, созданным функцией asynchronous generator.Added in version 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__()
.Added in version 3.11.
- 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), наборы и члены. Последние два типа определены в языке C, и для них существуют более специфические тесты, которые устойчивы к различным реализациям Python. Обычно дескрипторы данных также имеют атрибуты__name__
и__doc__
(свойства, гетсеты и члены имеют оба этих атрибута), но это не гарантировано.
- inspect.isgetsetdescriptor(object)¶
Возвращает
True
, если объект является дескриптором getset.Детали реализации CPython: Гетсеты - это атрибуты, определенные в модулях расширения через структуры
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
.
- inspect.getsource(object)¶
Возвращает текст исходного кода для объекта. Аргументом может быть модуль, класс, метод, функция, трассировка, фрейм или объект кода. Исходный код возвращается в виде одной строки. Если исходный код не может быть получен, выдается сообщение
OSError
. Если объект является встроенным модулем, классом или функцией, выдается сообщениеTypeError
.
- inspect.cleandoc(doc)¶
Очистите отступы в строках документов, которые выстраиваются в линию с блоками кода.
Все ведущие пробельные символы удаляются из первой строки. Со второй строки удаляются все пробельные символы, которые могут быть равномерно удалены. После этого удаляются пустые строки в начале и в конце. Кроме того, все табуляции расширяются до пробелов.
Интроспекция вызываемых файлов с помощью объекта Signature¶
Added in version 3.3.
Объект 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.__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()
илиcopy.replace()
, чтобы создать измененную копию.Изменено в версии 3.5: Объекты
Signature
теперь можно мариновать, а hashable- empty¶
Специальный маркер уровня класса, указывающий на отсутствие аннотации возврата.
- parameters¶
Упорядоченное отображение имен параметров на соответствующие объекты
Parameter
. Параметры отображаются в строгом порядке определения, включая параметры только с ключевыми словами.Изменено в версии 3.7: Python явно гарантировал сохранение порядка объявления параметров, относящихся только к ключевым словам, только начиная с версии 3.7, хотя на практике этот порядок всегда сохранялся в Python 3.
- return_annotation¶
Аннотация «return» для вызываемого объекта. Если вызываемый объект не имеет аннотации «return», этот атрибут устанавливается в
Signature.empty
.
- bind(*args, **kwargs)¶
Создает отображение позиционных и ключевых аргументов на параметры. Возвращает
BoundArguments
, если*args
и**kwargs
соответствуют сигнатуре, или вызывает ошибкуTypeError
.
- bind_partial(*args, **kwargs)¶
Работает так же, как и
Signature.bind()
, но допускает пропуск некоторых необходимых аргументов (имитирует поведениеfunctools.partial()
). ВозвращаетBoundArguments
или вызывает ошибкуTypeError
, если переданные аргументы не соответствуют сигнатуре.
- replace(*[, parameters][, return_annotation])¶
Создает новый экземпляр
Signature
на основе экземпляраreplace()
, который был вызван. Можно передавать различные параметры и/или возвращаемую_аннотацию, чтобы переопределить соответствующие свойства базовой сигнатуры. Чтобы удалить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'"
Объекты
Signature
также поддерживаются родовой функциейcopy.replace()
.
- format(*, max_width=None)¶
Создайте строковое представление объекта
Signature
.Если передано значение max_width, метод попытается уместить подпись в строках не более max_width символов. Если длина подписи превышает max_width, все параметры будут располагаться в отдельных строках.
Added in version 3.13.
- 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()
.Added in version 3.5.
Изменено в версии 3.10: Добавлены параметры globals, locals и eval_str.
- class inspect.Parameter(name, kind, *, default=Parameter.empty, annotation=Parameter.empty)¶
Объекты
Parameter
являются неизменяемыми. Вместо того чтобы изменять объектParameter
, вы можете использоватьParameter.replace()
илиcopy.replace()
для создания измененной копии.Изменено в версии 3.5: Объекты параметров теперь являются picklable и hashable.
- 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
.Added in version 3.8.
Пример: вывести все описания аргументов:
>>> def foo(a, b, *, c, d=10): ... pass >>> sig = signature(foo) >>> for param in sig.parameters.values(): ... print(param.kind.description) positional or keyword positional or keyword keyword-only keyword-only
- replace(*[, name][, kind][, default][, annotation])¶
Создайте новый экземпляр
Parameter
на основе экземпляра, для которого была вызвана функция replace. Чтобы переопределить атрибутParameter
, передайте соответствующий аргумент. Чтобы удалить значение по умолчанию или/и аннотацию изParameter
, передайтеParameter.empty
.>>> from inspect import Parameter >>> param = Parameter('foo', Parameter.KEYWORD_ONLY, default=42) >>> str(param) 'foo=42' >>> str(param.replace()) # Will create a shallow copy of 'param' 'foo=42' >>> str(param.replace(default=Parameter.empty, annotation='spam')) "foo: 'spam'"
Объекты
Parameter
также поддерживаются родовой функциейcopy.replace()
.
Изменено в версии 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
.
- 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': ()}
Added in version 3.5.
Свойства
args
иkwargs
можно использовать для вызова функций:def test(a, *, b): ... sig = signature(test) ba = sig.bind(10, b=20) test(*ba.args, **ba.kwargs)
См.также
- PEP 362 - Сигнатура функции Объект.
Подробная спецификация, детали реализации и примеры.
Классы и функции¶
- inspect.getclasstree(classes, unique=False)¶
Расположите заданный список классов в виде иерархии вложенных списков. Если появляется вложенный список, то он содержит классы, производные от класса, запись которого находится непосредственно перед списком. Каждая запись представляет собой кортеж, содержащий класс и кортеж его базовых классов. Если аргумент 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 на значения по умолчанию, используемые в случае отсутствия аргументов. annotations - словарь, отображающий имена параметров на аннотации. Специальный ключ"return"
используется для сообщения аннотации возвращаемого значения функции (если таковая имеется).Обратите внимание, что
signature()
и Signature Object предоставляют рекомендуемый API для вызываемой интроспекции и поддерживают дополнительное поведение (например, только позиционные аргументы), которое иногда встречается в API модулей расширения. Эта функция сохраняется в основном для использования в коде, который должен поддерживать совместимость с API модулей Python 2inspect
.Изменено в версии 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])¶
Форматирует красивый аргумент spec из четырех значений, возвращаемых
getargvalues()
. Аргументы format* - это соответствующие необязательные функции форматирования, которые вызываются для преобразования имен и значений в строки.Примечание
Эта функция по ошибке была помечена как устаревшая в Python 3.5.
- inspect.getmro(cls)¶
Возвращает кортеж базовых классов класса cls, включая cls, в порядке разрешения методов. Ни один класс не встречается в этом кортеже более одного раза. Обратите внимание, что порядок разрешения методов зависит от типа cls. Если только не используется очень своеобразный пользовательский метатип, cls будет первым элементом кортежа.
- inspect.getcallargs(func, /, *args, **kwds)¶
Свяжите args и kwds с именами аргументов Python-функции или метода func, как если бы он был вызван с ними. Для связанных методов привяжите также первый аргумент (обычно с именем
self
) к связанному экземпляру. Возвращается диктант, отображающий имена аргументов (включая имена аргументов*
и**
, если они есть) на их значения из args и kwds. В случае некорректного вызова func, т. е. когдаfunc(*args, **kwds)
вызвал бы исключение из-за несовместимой сигнатуры, будет вызвано исключение того же типа и с тем же или аналогичным сообщением. Например:>>> from inspect import getcallargs >>> def f(a, b=1, *pos, **named): ... pass ... >>> getcallargs(f, 1, 2, 3) == {'a': 1, 'named': {}, 'b': 2, 'pos': (3,)} True >>> getcallargs(f, a=2, x=4) == {'a': 2, 'named': {'x': 4}, 'b': 1, 'pos': ()} True >>> getcallargs(f) Traceback (most recent call last): ... TypeError: f() missing 1 required positional argument: 'a'
Added in version 3.2.
Не рекомендуется, начиная с версии 3.5: Вместо этого используйте
Signature.bind()
иSignature.bind_partial()
.
- inspect.getclosurevars(func)¶
Получает отображение ссылок на внешние имена в функции или методе Python func на их текущие значения. A named tuple
ClosureVars(nonlocals, globals, builtins, unbound)
возвращается. nonlocals сопоставляет имена ссылок с лексическими переменными закрытия, globals - с глобальными переменными модуля функции, а builtins - со встроенными переменными, видимыми из тела функции. unbound - это набор имен, на которые ссылается функция и которые не могут быть разрешены с учетом текущих глобалов модуля и buildins.TypeError
возникает, если func не является функцией или методом Python.Added in version 3.3.
- inspect.unwrap(func, *, stop=None)¶
Получает объект, обернутый func. Он следует по цепочке атрибутов
__wrapped__
, возвращая последний объект в цепочке.stop - необязательный обратный вызов, принимающий в качестве единственного аргумента объект в цепочке обёрток, который позволяет завершить разворачивание досрочно, если обратный вызов возвращает истинное значение. Если обратный вызов никогда не вернет истинное значение, последний объект в цепочке будет возвращен как обычно. Например,
signature()
использует это, чтобы остановить разворачивание, если у любого объекта в цепочке определен атрибут__signature__
.ValueError
поднимается, если встречается цикл.Added in version 3.4.
- inspect.get_annotations(obj, *, globals=None, locals=None, eval_str=False)¶
Вычислите дикту аннотаций для объекта.
obj
может быть вызываемым объектом, классом или модулем. Передача объекта любого другого типа приводит к появлениюTypeError
.Возвращает дикту.
get_annotations()
при каждом вызове возвращает новую дикту; если вызвать ее дважды на одном и том же объекте, то будут возвращены две разные, но эквивалентные дикты.Эта функция обрабатывает несколько деталей за вас:
Если значение
eval_str
равно true, значения типаstr
будут разгруппированы с помощьюeval()
. Это предназначено для использования со строковыми аннотациями (from __future__ import annotations
).Если у
obj
нет дикта аннотаций, возвращается пустой дикт. (Функции и методы всегда имеют дикту аннотаций; классы, модули и другие типы вызываемых объектов могут не иметь).Игнорирует унаследованные аннотации классов. Если класс не имеет собственной дикты аннотаций, возвращается пустая дикта.
Все обращения к членам объекта и значениям 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
является лучшей практикой для доступа к дикте аннотаций любого объекта. Дополнительные сведения о лучших практиках использования аннотаций см. в разделе Лучшие практики использования аннотаций.Added in version 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).
Примечание
Сохранение ссылок на объекты фрейма, которые находятся в первом элементе записей фрейма, возвращаемых этими функциями, может привести к созданию циклов ссылок в вашей программе. После создания цикла ссылок время жизни всех объектов, к которым можно получить доступ из объектов, образующих цикл, может значительно увеличиться, даже если в Python включен дополнительный детектор циклов. Если такие циклы должны быть созданы, важно обеспечить их явный разрыв, чтобы избежать задержки уничтожения объектов и повышенного потребления памяти.
Хотя детектор циклов будет их ловить, уничтожение фреймов (и локальных переменных) можно сделать детерминированным, удалив цикл в предложении finally
. Это также важно, если детектор циклов был отключен при компиляции Python или при использовании gc.disable()
. Например:
def handle_stackframe_without_leak():
frame = inspect.currentframe()
try:
# do something with the frame
finally:
del frame
Если вы хотите сохранить фрейм (например, чтобы позже вывести трассировку), вы также можете разорвать циклы ссылок с помощью метода frame.clear()
.
Необязательный аргумент context, поддерживаемый большинством этих функций, задает количество возвращаемых строк контекста, которые центрируются вокруг текущей строки.
- inspect.getframeinfo(frame, context=1)¶
Получение информации о кадре или объекте traceback. Возвращается объект
Traceback
.Изменено в версии 3.11: Вместо именованного кортежа возвращается объект
Traceback
.
- inspect.getouterframes(frame, context=1)¶
Получает список объектов
FrameInfo
для кадра и всех внешних кадров. Эти фреймы представляют вызовы, которые привели к созданию фрейма. Первая запись в возвращаемом списке представляет фрейм; последняя запись представляет крайний вызов в стеке фрейма.Изменено в версии 3.5: Возвращается список named tuples
FrameInfo(frame, filename, lineno, function, code_context, index)
возвращается.Изменено в версии 3.11: Возвращается список объектов
FrameInfo
.
- inspect.getinnerframes(traceback, context=1)¶
Получает список объектов
FrameInfo
для фрейма трассировки и всех внутренних фреймов. Эти кадры представляют вызовы, сделанные в результате выполнения кадра. Первая запись в списке представляет traceback; последняя запись представляет место, где было поднято исключение.Изменено в версии 3.5: Возвращается список named tuples
FrameInfo(frame, filename, lineno, function, code_context, index)
возвращается.Изменено в версии 3.11: Возвращается список объектов
FrameInfo
.
- inspect.currentframe()¶
Возвращает объект фрейма для фрейма стека вызывающей стороны.
Детали реализации 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__
затенен другим членом (например, свойством), то эта функция не сможет найти члены экземпляра.Added in version 3.2.
getattr_static()
не разрешает дескрипторы, например, дескрипторы слотов или дескрипторы getset для объектов, реализованных на языке C. Вместо базового атрибута возвращается объект дескриптора.
Вы можете обрабатывать их с помощью кода, подобного следующему. Обратите внимание, что для произвольных дескрипторов getset их вызов может вызвать выполнение кода:
# example code for resolving the builtin descriptor types
class _foo:
__slots__ = ['foo']
slot_descriptor = type(_foo.foo)
getset_descriptor = type(type(open(__file__)).name)
wrapper_descriptor = type(str.__dict__['__add__'])
descriptor_types = (slot_descriptor, getset_descriptor, wrapper_descriptor)
result = getattr_static(some_object, 'foo')
if type(result) in descriptor_types:
try:
result = result.__get__()
except AttributeError:
# descriptors can raise AttributeError to
# indicate there is no underlying value
# in which case the descriptor itself will
# have to do
pass
Современное состояние генераторов, коротинов и асинхронных генераторов¶
При реализации планировщиков корутинов и при других расширенных вариантах использования генераторов полезно определить, выполняется ли генератор в данный момент, ожидает начала или возобновления выполнения или уже завершился. getgeneratorstate()
позволяет легко определить текущее состояние генератора.
- inspect.getgeneratorstate(generator)¶
Получение текущего состояния генератора-итератора.
Возможны следующие состояния:
GEN_CREATED: Ожидание начала выполнения.
GEN_RUNNING: В настоящее время выполняется интерпретатором.
GEN_SUSPENDED: В настоящее время приостановлен на выражении yield.
GEN_CLOSED: Выполнение завершено.
Added in version 3.2.
- inspect.getcoroutinestate(coroutine)¶
Получение текущего состояния объекта coroutine. Функция предназначена для использования с объектами coroutine, созданными функциями
async def
, но может принимать любой coroutine-подобный объект, имеющий атрибутыcr_running
иcr_frame
.Возможны следующие состояния:
CORO_CREATED: Ожидание начала выполнения.
CORO_RUNNING: В настоящее время выполняется интерпретатором.
CORO_SUSPENDED: В настоящее время выполнение приостановлено на выражении await.
CORO_CLOSED: Выполнение завершено.
Added in version 3.5.
- inspect.getasyncgenstate(agen)¶
Получение текущего состояния объекта асинхронного генератора. Функция предназначена для использования с объектами асинхронных итераторов, созданных функциями
async def
, использующими операторyield
, но может принимать любой асинхронный генератороподобный объект, имеющий атрибутыag_running
иag_frame
.Возможны следующие состояния:
AGEN_CREATED: Ожидание начала выполнения.
AGEN_RUNNING: В настоящее время выполняется интерпретатором.
AGEN_SUSPENDED: В настоящее время приостановлен на выражении доходности.
AGEN_CLOSED: Выполнение завершено.
Added in version 3.12.
Также можно запросить текущее внутреннее состояние генератора. В основном это полезно для целей тестирования, чтобы убедиться, что внутреннее состояние обновляется так, как ожидается:
- inspect.getgeneratorlocals(generator)¶
Получает отображение локальных переменных в generator на их текущие значения. Возвращается словарь, в котором имена переменных сопоставляются со значениями. Это эквивалентно вызову
locals()
в теле генератора, и действуют те же предостережения.Если generator - это generator без связанного с ним кадра, то возвращается пустой словарь. Если generator не является объектом генератора Python, то возвращается
TypeError
.Детали реализации CPython: Эта функция полагается на то, что генератор раскрывает кадр стека Python для интроспекции, что не гарантируется во всех реализациях Python. В таких случаях эта функция всегда будет возвращать пустой словарь.
Added in version 3.3.
- inspect.getcoroutinelocals(coroutine)¶
Эта функция аналогична
getgeneratorlocals()
, но работает для объектов coroutine, созданных функциямиasync def
.Added in version 3.5.
- inspect.getasyncgenlocals(agen)¶
Эта функция аналогична
getgeneratorlocals()
, но работает для объектов асинхронных генераторов, созданных функциямиasync def
, которые используют операторyield
.Added in version 3.12.
Битовые флаги кодовых объектов¶
Объекты кода Python имеют атрибут co_flags
, который представляет собой битовое изображение следующих флагов:
- inspect.CO_OPTIMIZED¶
Код объекта оптимизирован и использует быстрые локали.
- inspect.CO_NEWLOCALS¶
Если установлено, то при выполнении объекта кода для
f_locals
кадра будет создан новый dict.
- inspect.CO_VARARGS¶
Объект кода имеет переменный позиционный параметр (
*args
-подобный).
- inspect.CO_VARKEYWORDS¶
Объект кода имеет переменный ключевой параметр (
**kwargs
-подобный).
- inspect.CO_NESTED¶
Флаг устанавливается, когда объект кода является вложенной функцией.
- inspect.CO_GENERATOR¶
Флаг устанавливается, если объект кода является функцией-генератором, т.е. при выполнении объекта кода возвращается объект-генератор.
- inspect.CO_COROUTINE¶
Флаг устанавливается, когда объект кода является коревой функцией. Когда объект кода выполняется, он возвращает объект coroutine. Более подробную информацию см. в разделе PEP 492.
Added in version 3.5.
- inspect.CO_ITERABLE_COROUTINE¶
Флаг используется для преобразования генераторов в корутины на основе генераторов. Объекты генераторов с этим флагом могут использоваться в
await
выражениях, а объектыyield from
короутинов. Более подробную информацию см. в разделе PEP 492.Added in version 3.5.
- inspect.CO_ASYNC_GENERATOR¶
Флаг устанавливается, если объект кода является функцией асинхронного генератора. При выполнении объекта кода он возвращает объект асинхронного генератора. Более подробную информацию см. в разделе PEP 525.
Added in version 3.6.
Примечание
Флаги специфичны для CPython и не могут быть определены в других реализациях Python. Кроме того, флаги являются деталями реализации и могут быть удалены или устаревшими в будущих релизах Python. Рекомендуется использовать публичные API из модуля inspect
для любых потребностей в интроспекции.
Флаги буфера¶
- class inspect.BufferFlags¶
Это
enum.IntFlag
, представляющий флаги, которые могут быть переданы методу__buffer__()
объектов, реализующих buffer protocol.Значение флагов объясняется в Типы буферных запросов.
- SIMPLE¶
- WRITABLE¶
- FORMAT¶
- ND¶
- STRIDES¶
- C_CONTIGUOUS¶
- F_CONTIGUOUS¶
- ANY_CONTIGUOUS¶
- INDIRECT¶
- CONTIG¶
- CONTIG_RO¶
- STRIDED¶
- STRIDED_RO¶
- RECORDS¶
- RECORDS_RO¶
- FULL¶
- FULL_RO¶
- READ¶
- WRITE¶
Added in version 3.12.
Интерфейс командной строки¶
Модуль inspect
также предоставляет базовую возможность интроспекции из командной строки.
По умолчанию принимает имя модуля и печатает его источник. Вместо этого можно вывести класс или функцию внутри модуля, добавив двоеточие и квалифицированное имя целевого объекта.
- --details¶
Выведите информацию об указанном объекте, а не исходный код