inspect.md

1> **Источник:** https://python-all.ru/3.0/library/inspect.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# `inspect` – Инспекция живых объектов89Модуль `inspect` предоставляет несколько полезных функций для получения информации о работающих объектах, таких как модули, классы, методы, функции, трассировки, объекты фреймов и объекты кода. Например, он может помочь изучить содержимое класса, получить исходный код метода, извлечь и отформатировать список аргументов функции или получить всю информацию, необходимую для отображения подробной трассировки.1011Этот модуль предоставляет четыре основных вида сервисов: проверка типов, получение исходного кода, инспекция классов и функций, а также анализ стека интерпретатора.1213## Типы и члены1415Функция [`getmembers()`](https://python-all.ru/3.0/library/inspect.html#inspect.getmembers) извлекает члены объекта, такого как класс или модуль. Шестнадцать функций, имена которых начинаются с «is», в основном предоставляются как удобные варианты для второго аргумента [`getmembers()`](https://python-all.ru/3.0/library/inspect.html#inspect.getmembers). Они также помогают определить, когда можно ожидать следующие специальные атрибуты:1617| Тип | Атрибут | Описание |18| --- | --- | --- |19| модуль | doc | строка документации |20|  | file | filename (отсутствует для встроенных модулей) |21| класс | doc | строка документации |22|  | module | имя модуля, в котором был определён этот класс |23| метод | doc | строка документации |24|  | name | имя, под которым был определён этот метод |25|  | func | объект функции, содержащий реализацию метода |26|  | self | экземпляр, к которому привязан этот метод, или `None` |27| функция | doc | строка документации |28|  | name | имя, под которым была определена эта функция |29|  | code | объект кода, содержащий скомпилированную функцию [*байткод*](https://python-all.ru/3.0/glossary.html#term-bytecode) |30|  | defaults | кортеж значений по умолчанию для аргументов |31|  | globals | глобальное пространство имён, в котором была определена эта функция |32| трассировка | tb\_frame | объект фрейма на этом уровне |33|  | tb\_lasti | индекс последней предпринятой инструкции в байткоде |34|  | tb\_lineno | текущий номер строки в исходном коде Python |35|  | tb\_next | следующий внутренний объект traceback (вызванный на этом уровне) |36| фрейм | f\_back | следующий внешний объект фрейма (вызывающий этот фрейм) |37|  | f\_builtins | встроенное пространство имён, видимое данным фреймом |38|  | f\_code | объект кода, выполняющийся в этом фрейме |39|  | f\_globals | глобальное пространство имён, видимое этим фреймом |40|  | f\_lasti | индекс последней предпринятой инструкции в байткоде |41|  | f\_lineno | текущий номер строки в исходном коде Python |42|  | f\_locals | локальное пространство имён, видимое этим фреймом |43|  | f\_restricted | 0 или 1, если фрейм находится в ограниченном режиме выполнения |44|  | f\_trace | функция трассировки для этого фрейма, или `None` |45| код | co\_argcount | количество аргументов (не включая \* или \*\* args) |46|  | co\_code | строка сырого скомпилированного байткода |47|  | co\_consts | кортеж констант, используемых в байткоде |48|  | co\_filename | имя файла, в котором был создан этот объект кода |49|  | co\_firstlineno | номер первой строки в исходном коде Python |50|  | co\_flags | битовая маска: 1=оптимизировано `\|` 2=новые локальные `\|` 4=\*arg `\|` 8=\*\*arg |51|  | co\_lnotab | кодированное отображение номеров строк на индексы байт-кода |52|  | co\_name | имя, с которым был определён этот объект кода |53|  | co\_names | кортеж имён локальных переменных |54|  | co\_nlocals | количество локальных переменных |55|  | co\_stacksize | требуемый размер стека виртуальной машины |56|  | co\_varnames | кортеж имён аргументов и локальных переменных |57| встроенный | doc | строка документации |58|  | name | исходное имя этой функции или метода |59|  | self | экземпляр, к которому привязан метод, или `None` |6061#### `[inspect.getmembers]inspect.getmembers(object[, predicate])`6263Возвращает все члены объекта в виде списка пар (имя, значение), отсортированных по имени. Если передан необязательный аргумент *predicate*, включаются только те члены, для которых предикат возвращает истинное значение.6465> **Примечание**66>67> [`getmembers()`](https://python-all.ru/3.0/library/inspect.html#inspect.getmembers) не возвращает атрибуты метакласса, когда аргумент является классом (это поведение унаследовано от функции [`dir()`](https://python-all.ru/3.0/library/functions.html#dir)).6869#### `[inspect.getmoduleinfo]inspect.getmoduleinfo(path)`7071Возвращает7273[*именованный кортеж*](https://python-all.ru/3.0/glossary.html#term-named-tuple)7475`ModuleInfo(name, suffix, mode, module_type)`7677значений, описывающих, как Python будет интерпретировать файл, определяемый7879*path*8081, если это модуль, или8283`None`8485, если он не будет распознан как модуль. Возвращаемый кортеж выглядит как8687`(name, suffix, mode, mtype)`8889, где9091*name*9293– это имя модуля без имени любого включающего пакета,9495*suffix*9697– конечная часть имени файла (которая может не быть расширением, отделённым точкой),9899*mode*100101– это режим102103[`open()`](https://python-all.ru/3.0/library/functions.html#open)104105, который будет использован (106107`'r'`108109или110111`'rb'`112113), а114115*mtype*116117– это целое число, указывающее тип модуля.118119*mtype*120121будет иметь значение, которое можно сравнивать с константами, определёнными в модуле122123[`imp`](https://python-all.ru/3.0/library/imp.html#module-imp)124125; смотрите документацию по этому модулю для получения дополнительной информации о типах модулей.126127#### `[inspect.getmodulename]inspect.getmodulename(path)`128129Возвращает имя модуля, задаваемое файлом130131*path*132133, без включения имён объемлющих пакетов. Используется тот же алгоритм, что и интерпретатор при поиске модулей. Если имя не удаётся сопоставить по правилам интерпретатора, возвращается134135`None`136137.138139#### `[inspect.ismodule]inspect.ismodule(object)`140141Возвращает True, если объект является модулем.142143#### `[inspect.isclass]inspect.isclass(object)`144145Возвращает True, если объект является классом.146147#### `[inspect.ismethod]inspect.ismethod(object)`148149Возвращает True, если объект является методом.150151#### `[inspect.isfunction]inspect.isfunction(object)`152153Возвращает True, если объект является функцией Python или анонимной (154155[*lambda*](https://python-all.ru/3.0/glossary.html#term-lambda)156157) функцией.158159#### `[inspect.isgeneratorfunction]inspect.isgeneratorfunction(object)`160161Возвращает True, если объект является функцией-генератором Python.162163#### `[inspect.isgenerator]inspect.isgenerator(object)`164165Возвращает True, если объект является генератором.166167#### `[inspect.istraceback]inspect.istraceback(object)`168169Возвращает True, если объект является трассировкой.170171#### `[inspect.isframe]inspect.isframe(object)`172173Возвращает True, если объект является фреймом.174175#### `[inspect.iscode]inspect.iscode(object)`176177Возвращает True, если объект является кодом.178179#### `[inspect.isbuiltin]inspect.isbuiltin(object)`180181Возвращает True, если объект является встроенной функцией.182183#### `[inspect.isroutine]inspect.isroutine(object)`184185Возвращает True, если объект является пользовательской или встроенной функцией или методом.186187#### `[inspect.isabstract]inspect.isabstract(object)`188189Возвращает True, если объект является абстрактным базовым классом.190191#### `[inspect.ismethoddescriptor]inspect.ismethoddescriptor(object)`192193Возвращает True, если объект является дескриптором метода, но не в случаях, когда [`ismethod()`](https://python-all.ru/3.0/library/inspect.html#inspect.ismethod)\\nили [`isclass()`](https://python-all.ru/3.0/library/inspect.html#inspect.isclass), или [`isfunction()`](https://python-all.ru/3.0/library/inspect.html#inspect.isfunction) возвращают True.194195Это, например, верно для `int.__add__`. Объект, проходящий эту проверку, имеет атрибут `__get__`, но не имеет атрибута `__set__`, а кроме того, набор атрибутов различается. `__name__` обычно осмысленно, и `__doc__` часто тоже.196197Методы, реализованные через дескрипторы и также проходящие один из других тестов, возвращают false для теста [`ismethoddescriptor()`](https://python-all.ru/3.0/library/inspect.html#inspect.ismethoddescriptor) просто потому, что другие тесты обещают больше – например, можно рассчитывать на наличие атрибута `__func__` (и т.д.), когда объект проходит [`ismethod()`](https://python-all.ru/3.0/library/inspect.html#inspect.ismethod).198199#### `[inspect.isdatadescriptor]inspect.isdatadescriptor(object)`200201Возвращает True, если объект является дескриптором данных.202203Дескрипторы данных имеют как атрибут `__get__`, так и атрибут `__set__`. Примеры: свойства (определённые в Python), getsets и элементы. Последние два определены на C, и для этих типов существуют более специфичные проверки, которые работают во всех реализациях Python. Обычно дескрипторы данных также имеют атрибуты `__name__` и `__doc__` (свойства, getsets и элементы имеют оба этих атрибута), но это не гарантируется.204205#### `[inspect.isgetsetdescriptor]inspect.isgetsetdescriptor(object)`206207Возвращает True, если объект является дескриптором getset.208209Getsets – это атрибуты, определенные в модулях расширения через `PyGetSetDef`\\nструктуры. Для реализаций Python, в которых нет таких типов, этот метод\\nвсегда возвращает `False`.210211#### `[inspect.ismemberdescriptor]inspect.ismemberdescriptor(object)`212213Возвращает True, если объект является дескриптором члена.214215Дескрипторы членов – это атрибуты, определенные в модулях расширения через\\nструктуры `PyMemberDef`. Для реализаций Python без таких типов\\nэтот метод всегда возвращает `False`.216217## Получение исходного кода218219#### `[inspect.getdoc]inspect.getdoc(object)`220221Возвращает строку документации объекта, очищенную с помощью222223[`cleandoc()`](https://python-all.ru/3.0/library/inspect.html#inspect.cleandoc)224225.226227#### `[inspect.getcomments]inspect.getcomments(object)`228229Возвращает единой строкой все строки комментариев, непосредственно предшествующие исходному коду объекта (для класса, функции или метода) или находящиеся в начале исходного файла Python (если объект – модуль).230231#### `[inspect.getfile]inspect.getfile(object)`232233Возвращает имя (текстового или бинарного) файла, в котором определён объект. Это вызовет234235[`TypeError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.TypeError)236237, если объект является встроенным модулем, классом или функцией.238239#### `[inspect.getmodule]inspect.getmodule(object)`240241Пытается определить модуль, в котором был определён объект.242243#### `[inspect.getsourcefile]inspect.getsourcefile(object)`244245Возвращает имя исходного файла Python, в котором определён объект. Это вызовет246247[`TypeError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.TypeError)248249, если объект является встроенным модулем, классом или функцией.250251#### `[inspect.getsourcelines]inspect.getsourcelines(object)`252253Возвращает список строк исходного кода и номер начальной строки для объекта. Аргументом может быть модуль, класс, метод, функция, трассировка, фрейм или объект кода. Исходный код возвращается в виде списка строк, соответствующих объекту, а номер строки указывает, где в исходном файле была найдена первая строка кода. Возбуждается исключение254255[`IOError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.IOError)256257, если исходный код не удается получить.258259#### `[inspect.getsource]inspect.getsource(object)`260261Возвращает текст исходного кода для объекта. Аргументом может быть модуль, класс, метод, функция, трассировка, фрейм или объект кода. Исходный код возвращается в виде одной строки. Возбуждается исключение262263[`IOError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.IOError)264265, если исходный код не удается получить.266267#### `[inspect.cleandoc]inspect.cleandoc(doc)`268269Убирает отступы из строк документации, которые добавлены для выравнивания с блоками кода. Удаляются все пробельные символы, которые можно равномерно убрать, начиная со второй строки. Также все табуляции заменяются пробелами.270271## Классы и функции272273#### `[inspect.getclasstree]inspect.getclasstree(classes[, unique])`274275Упорядочивает заданный список классов в иерархию вложенных списков. Если встречается вложенный список, он содержит классы, унаследованные от класса, запись которого непосредственно предшествует этому списку. Каждая запись представляет собой кортеж из двух элементов, содержащий класс и кортеж его базовых классов. Если аргумент276277*unique*278279равен true, в возвращаемой структуре появляется ровно одна запись для каждого класса из заданного списка. В противном случае классы, использующие множественное наследование, и их потомки будут появляться несколько раз.280281#### `[inspect.getargspec]inspect.getargspec(func)`282283Получить имена и значения по умолчанию аргументов функции. Возвращается [*именованный кортеж*](https://python-all.ru/3.0/glossary.html#term-named-tuple) `ArgSpec(args, varargs, keywords, defaults)`. *args* – это список имён аргументов. *varargs* и *varkw* – это имена аргументов `*` и `**` или `None`. *defaults* – это кортеж значений аргументов по умолчанию или None, если аргументов по умолчанию нет; если этот кортеж содержит *n* элементов, они соответствуют последним *n* элементам из списка *args*.284285Устарело с версии 3.0: Вместо этого используйте [`getfullargspec()`](https://python-all.ru/3.0/library/inspect.html#inspect.getfullargspec), который предоставляет информацию об именованных аргументах (keyword-only) и аннотациях.286287#### `[inspect.getfullargspec]inspect.getfullargspec(func)`288289Получить имена и значения по умолчанию аргументов функции. [*Именованный кортеж*](https://python-all.ru/3.0/glossary.html#term-named-tuple) возвращается:290291`FullArgSpec(args, varargs, varkw, defaults, kwonlyargs, kwonlydefaults, annotations)`292293*args* – список имён аргументов. *varargs* и *varkw* – имена аргументов `*` и `**` или `None`. *defaults* – n-кортеж значений по умолчанию для последних n аргументов. *kwonlyargs* – список имён только ключевых аргументов. *kwonlydefaults* – словарь, сопоставляющий имена из kwonlyargs значениям по умолчанию. *annotations* – словарь, сопоставляющий имена аргументов аннотациям.294295Первые четыре элемента в кортеже соответствуют [`getargspec()`](https://python-all.ru/3.0/library/inspect.html#inspect.getargspec).296297#### `[inspect.getargvalues]inspect.getargvalues(frame)`298299Получить информацию об аргументах, переданных в конкретный фрейм. Возвращается300301[*именованный кортеж*](https://python-all.ru/3.0/glossary.html#term-named-tuple)302303`ArgInfo(args, varargs, keywords, locals)`304305.306307*args*308309– это список имён аргументов (может содержать вложенные списки).310311*varargs*312313и314315*varkw*316317– это имена аргументов318319`*`320321и322323`**`324325или326327`None`328329.330331*locals*332333– это словарь locals данного фрейма.334335#### `[inspect.formatargspec]inspect.formatargspec(args[, varargs, varkw, defaults, formatarg, formatvarargs, formatvarkw, formatvalue, join])`336337Форматирует читаемое описание аргументов из четырёх значений, возвращаемых338339[`getargspec()`](https://python-all.ru/3.0/library/inspect.html#inspect.getargspec)340341. Аргументы format\* – это соответствующие необязательные функции форматирования, которые вызываются для преобразования имён и значений в строки.342343#### `[inspect.formatargvalues]inspect.formatargvalues(args[, varargs, varkw, locals, formatarg, formatvarargs, formatvarkw, formatvalue, join])`344345Форматирует красивое описание аргументов из четырёх значений, возвращаемых346347[`getargvalues()`](https://python-all.ru/3.0/library/inspect.html#inspect.getargvalues)348349. Аргументы format\* – это соответствующие необязательные функции форматирования, которые вызываются для преобразования имён и значений в строки.350351#### `[inspect.getmro]inspect.getmro(cls)`352353Возвращает кортеж базовых классов класса cls, включая cls, в порядке разрешения методов (MRO). Ни один класс не встречается в этом кортеже более одного раза. Обратите внимание, что порядок разрешения методов зависит от типа cls. Если не используется особенная пользовательская метатипизация, cls будет первым элементом кортежа.354355## Стек интерпретатора356357Когда следующие функции возвращают «записи фреймов» (frame records), каждая запись представляет собой кортеж из шести элементов: объект фрейма, имя файла, номер текущей строки, имя функции, список строк контекста из исходного кода и индекс текущей строки в этом списке.358359> **Предупреждение**360>361> Хранение ссылок на объекты фреймов (как в первом элементе записей фреймов, возвращаемых этими функциями) может привести к созданию циклических ссылок в программе. После создания циклической ссылки время жизни всех объектов, доступных из объектов, образующих цикл, может значительно увеличиться, даже если включён дополнительный детектор циклов Python. Если такие циклы необходимо создать, важно убедиться, что они явно разрываются, чтобы избежать задержки уничтожения объектов и увеличения потребления памяти.362>363> Хотя детектор циклов перехватит их, уничтожение фреймов (и локальных переменных) можно сделать детерминированным, удалив цикл в блоке [`finally`](https://python-all.ru/3.0/reference/compound_stmts.html#finally). Это также важно, если детектор циклов был отключён при компиляции Python или с помощью [`gc.disable()`](https://python-all.ru/3.0/library/gc.html#gc.disable). Например:364>365> ```python366> def handle_stackframe_without_leak():367>     frame = inspect.currentframe()368>     try:369>         # Выполнить действие с фреймом370>     finally:371>         del frame372> ```373374Необязательный аргумент *context*, поддерживаемый большинством этих функций, задаёт количество возвращаемых строк контекста, которые располагаются вокруг текущей строки.375376#### `[inspect.getframeinfo]inspect.getframeinfo(frame[, context])`377378Возвращает информацию об объекте фрейма или traceback. Возвращается379380[*именованный кортеж*](https://python-all.ru/3.0/glossary.html#term-named-tuple)381382`Traceback(filename, lineno, function, code_context, index)`383384.385386#### `[inspect.getouterframes]inspect.getouterframes(frame[, context])`387388Возвращает список записей фреймов для фрейма и всех внешних фреймов. Эти фреймы представляют вызовы, которые привели к созданию389390*frame*391392. Первая запись в возвращаемом списке представляет393394*frame*395396; последняя запись представляет самый внешний вызов в стеке397398*frame*399400.401402#### `[inspect.getinnerframes]inspect.getinnerframes(traceback[, context])`403404Возвращает список записей о фреймах для фрейма traceback и всех внутренних фреймов. Эти фреймы представляют вызовы, являющиеся следствием405406*frame*407408. Первый элемент списка представляет409410*traceback*411412; последний элемент представляет место, где было возбуждено исключение.413414#### `[inspect.currentframe]inspect.currentframe()`415416Возвращает объект фрейма для фрейма стека вызывающего.417418#### `[inspect.stack]inspect.stack([context])`419420Возвращает список записей о фреймах для стека вызывающего кода. Первый элемент возвращаемого списка представляет вызывающий код; последний элемент представляет самый внешний вызов в стеке.421422#### `[inspect.trace]inspect.trace([context])`423424Возвращает список записей о фреймах для стека между текущим фреймом и фреймом, в котором было возбуждено исключение, обрабатываемое в данный момент. Первый элемент списка представляет вызывающий код; последний элемент представляет место, где было возбуждено исключение.425