inspect.md

1> **Источник:** https://python-all.ru/2.7/library/inspect.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# 28.13. [`inspect`](https://python-all.ru/2.7/library/inspect.html#module-inspect) – Инспекция активных объектов89Новое в версии 2.1.1011**Исходный код:** [Lib/inspect.py](https://python-all.ru/src/2.7/Lib/inspect.py)1213---1415Модуль [`inspect`](https://python-all.ru/2.7/library/inspect.html#module-inspect) предоставляет несколько полезных функций для получения информации о живых объектах, таких как модули, классы, методы, функции, трассировки, объекты кадров и объекты кода. Например, он позволяет изучить содержимое класса, получить исходный код метода, извлечь и отформатировать список аргументов функции или получить всю информацию, необходимую для вывода подробной трассировки.1617Этот модуль предоставляет четыре основных вида сервисов: проверка типов, получение исходного кода, инспекция классов и функций, а также анализ стека интерпретатора.1819## 28.13.1. Типы и члены2021Функция [`getmembers()`](https://python-all.ru/2.7/library/inspect.html#inspect.getmembers) извлекает члены объекта, такого как класс или модуль. Шестнадцать функций, имена которых начинаются с «is», в основном предоставлены как удобные варианты для второго аргумента [`getmembers()`](https://python-all.ru/2.7/library/inspect.html#inspect.getmembers). Они также помогают определить, когда можно ожидать следующие специальные атрибуты:2223| Тип | Атрибут | Описание | Примечания |24| --- | --- | --- | --- |25| модуль | doc | строка документации |  |26|  | file | filename (отсутствует для встроенных модулей) |  |27| класс | doc | строка документации |  |28|  | module | имя модуля, в котором был определён этот класс |  |29| метод | doc | строка документации |  |30|  | name | имя, под которым был определён этот метод |  |31|  | im\_class | объект класса, запросившего этот метод | (1) |32|  | im\_func или \_\_func\_\_ | объект функции, содержащий реализацию метода |  |33|  | im\_self или \_\_self\_\_ | экземпляр, к которому привязан этот метод, или `None` |  |34| функция | doc | строка документации |  |35|  | name | имя, под которым была определена эта функция |  |36|  | func\_code | объект кода, содержащий скомпилированную функцию [байткод](https://python-all.ru/2.7/glossary.html#term-bytecode) |  |37|  | func\_defaults | кортеж значений по умолчанию для аргументов |  |38|  | func\_doc | (то же, что и \_\_doc\_\_) |  |39|  | func\_globals | глобальное пространство имён, в котором была определена эта функция |  |40|  | func\_name | (то же, что и \_\_name\_\_) |  |41| генератор | iter | определён для поддержки итерации по контейнеру |  |42|  | close | возбуждает новое исключение GeneratorExit внутри генератора, чтобы завершить итерацию |  |43|  | gi\_code | объект кода |  |44|  | gi\_frame | объект фрейма или, возможно, `None` после того, как генератор был исчерпан |  |45|  | gi\_running | установлено в 1, когда генератор выполняется, иначе 0 |  |46|  | далее | возвращает следующий элемент из контейнера |  |47|  | send | возобновляет генератор и «отправляет» значение, которое становится результатом текущего yield-выражения |  |48|  | throw | используется для возбуждения исключения внутри генератора |  |49| трассировка | tb\_frame | объект фрейма на этом уровне |  |50|  | tb\_lasti | индекс последней предпринятой инструкции в байткоде |  |51|  | tb\_lineno | текущий номер строки в исходном коде Python |  |52|  | tb\_next | следующий внутренний объект traceback (вызванный на этом уровне) |  |53| фрейм | f\_back | следующий внешний объект фрейма (вызывающий этот фрейм) |  |54|  | f\_builtins | пространство имён builtins, видимое этим фреймом |  |55|  | f\_code | объект кода, выполняющийся в этом фрейме |  |56|  | f\_exc\_traceback | traceback, если возникло в этом кадре, или `None` |  |57|  | f\_exc\_type | тип исключения, если возникло в этом кадре, или `None` |  |58|  | f\_exc\_value | значение исключения, если возникло в этом кадре, или `None` |  |59|  | f\_globals | глобальное пространство имён, видимое этим фреймом |  |60|  | f\_lasti | индекс последней предпринятой инструкции в байткоде |  |61|  | f\_lineno | текущий номер строки в исходном коде Python |  |62|  | f\_locals | локальное пространство имён, видимое этим фреймом |  |63|  | f\_restricted | 0 или 1, если фрейм находится в ограниченном режиме выполнения |  |64|  | f\_trace | функция трассировки для этого фрейма или `None` |  |65| код | co\_argcount | количество аргументов (не включая \* или \*\* args) |  |66|  | co\_code | строка сырого скомпилированного байткода |  |67|  | co\_consts | кортеж констант, используемых в байткоде |  |68|  | co\_filename | имя файла, в котором был создан этот объект кода |  |69|  | co\_firstlineno | номер первой строки в исходном коде Python |  |70|  | co\_flags | битовая маска: 1=оптимизировано `\|` 2=новые локальные `\|` 4=\*arg `\|` 8=\*\*arg |  |71|  | co\_lnotab | кодированное отображение номеров строк на индексы байт-кода |  |72|  | co\_name | имя, с которым был определён этот объект кода |  |73|  | co\_names | кортеж имён локальных переменных |  |74|  | co\_nlocals | количество локальных переменных |  |75|  | co\_stacksize | требуемый размер стека виртуальной машины |  |76|  | co\_varnames | кортеж имён аргументов и локальных переменных |  |77| встроенный | doc | строка документации |  |78|  | name | исходное имя этой функции или метода |  |79|  | self | экземпляр, к которому привязан метод, или `None` |  |8081Примечание:82831. Изменено в версии 2.2: `im_class` ранее ссылался на класс, который определил метод.8485#### `inspect.getmembers(object[, predicate])`8687Возвращает все члены объекта в виде списка пар (имя, значение), отсортированных по имени. Если передан необязательный аргумент *predicate*, включаются только те члены, для которых предикат возвращает истинное значение.8889> **Примечание**90>91> [`getmembers()`](https://python-all.ru/2.7/library/inspect.html#inspect.getmembers) не возвращает атрибуты метакласса, когда аргумент является классом (это поведение наследуется от функции [`dir()`](https://python-all.ru/2.7/library/functions.html#dir)).9293#### `inspect.getmoduleinfo(path)`9495Возвращает кортеж значений, описывающих, как Python будет интерпретировать файл идентифицируемый *путь*, если это модуль, или `None`, если он не будет идентифицирован как модуль. Возвращаемый кортеж – `(name, suffix, mode, module_type)`, где *name* – имя модуля без имени какого-либо включающего пакета, *suffix* – завершающая часть имени файла (которая может не быть расширением, отделённым точкой), *mode* – режим [`open()`](https://python-all.ru/2.7/library/functions.html#open), который будет использован (`'r'` или `'rb'`), а *module\_type* – целое число, задающее тип модуля. *module\_type* будет иметь значение, которое можно сравнить с константами, определёнными в модуле [`imp`](https://python-all.ru/2.7/library/imp.html#module-imp); см. документацию этого модуля для получения дополнительной информации о типах модулей.9697Изменено в версии 2.6: Возвращает [именованный кортеж](https://python-all.ru/2.7/glossary.html#term-named-tuple) `ModuleInfo(name, suffix, mode, module_type)`.9899#### `inspect.getmodulename(path)`100101Возвращает имя модуля, заданного файлом *путь*, без включения имён включающих пакетов. При этом используется тот же алгоритм, что и интерпретатор использует при поиске модулей. Если имя не может быть сопоставлено согласно правилам интерпретатора, возвращается `None`.102103#### `inspect.ismodule(object)`104105Возвращает True, если объект является модулем.106107#### `inspect.isclass(object)`108109Возвращает True, если объект является классом, встроенным или созданным в коде Python.110111#### `inspect.ismethod(object)`112113Возвращает истину, если объект является связанным или несвязанным методом, написанным на Python.114115#### `inspect.isfunction(object)`116117Возвращает True, если объект является функцией Python, включая функции, созданные с помощью выражения [lambda](https://python-all.ru/2.7/glossary.html#term-lambda).118119#### `inspect.isgeneratorfunction(object)`120121Возвращает True, если объект является функцией-генератором Python.122123Новое в версии 2.6.124125#### `inspect.isgenerator(object)`126127Возвращает True, если объект является генератором.128129Новое в версии 2.6.130131#### `inspect.istraceback(object)`132133Возвращает True, если объект является трассировкой.134135#### `inspect.isframe(object)`136137Возвращает True, если объект является фреймом.138139#### `inspect.iscode(object)`140141Возвращает True, если объект является кодом.142143#### `inspect.isbuiltin(object)`144145Возвращает True, если объект является встроенной функцией или связанным встроенным методом.146147#### `inspect.isroutine(object)`148149Возвращает True, если объект является пользовательской или встроенной функцией или методом.150151#### `inspect.isabstract(object)`152153Возвращает True, если объект является абстрактным базовым классом.154155Новое в версии 2.6.156157#### `inspect.ismethoddescriptor(object)`158159Возвращает True, если объект является дескриптором метода, но не в случае, если [`ismethod()`](https://python-all.ru/2.7/library/inspect.html#inspect.ismethod), [`isclass()`](https://python-all.ru/2.7/library/inspect.html#inspect.isclass), [`isfunction()`](https://python-all.ru/2.7/library/inspect.html#inspect.isfunction) или [`isbuiltin()`](https://python-all.ru/2.7/library/inspect.html#inspect.isbuiltin) истинны.160161Это нововведение начиная с Python 2.2 и, например, верно для `int.__add__`. Объект, проходящий эту проверку, имеет метод [`__get__()`](https://python-all.ru/2.7/reference/datamodel.html#object.__get__), но не имеет метода [`__set__()`](https://python-all.ru/2.7/reference/datamodel.html#object.__set__), однако остальной набор атрибутов различается. Атрибут [`__name__`](https://python-all.ru/2.7/library/stdtypes.html#definition.__name__) обычно имеет смысл, а `__doc__` – часто.162163Методы, реализованные через дескрипторы, которые также проходят один из других тестов, возвращают false для теста [`ismethoddescriptor()`](https://python-all.ru/2.7/library/inspect.html#inspect.ismethoddescriptor), просто потому, что другие тесты обещают больше – например, можно рассчитывать на наличие атрибута `im_func` (и т.д.), когда объект проходит [`ismethod()`](https://python-all.ru/2.7/library/inspect.html#inspect.ismethod).164165#### `inspect.isdatadescriptor(object)`166167Возвращает True, если объект является дескриптором данных.168169Дескрипторы данных имеют оба метода – [`__get__`](https://python-all.ru/2.7/reference/datamodel.html#object.__get__) и [`__set__`](https://python-all.ru/2.7/reference/datamodel.html#object.__set__). Примерами являются свойства (определённые в Python), getsets и members. Последние два определены в C, и для этих типов существуют более специальные проверки, что надёжно во всех реализациях Python. Обычно дескрипторы данных также имеют атрибуты [`__name__`](https://python-all.ru/2.7/library/stdtypes.html#definition.__name__) и `__doc__` (свойства, getsets и members имеют оба этих атрибута), но это не гарантируется.170171Новое в версии 2.3.172173#### `inspect.isgetsetdescriptor(object)`174175Возвращает True, если объект является дескриптором getset.176177**Особенность реализации CPython:** getsets – это атрибуты, определённые в модулях расширения через структуры [`PyGetSetDef`](https://python-all.ru/2.7/c-api/structures.html#c.PyGetSetDef). Для реализаций Python без таких типов этот метод всегда будет возвращать `False`.178179Новое в версии 2.5.180181#### `inspect.ismemberdescriptor(object)`182183Возвращает True, если объект является дескриптором члена.184185**Особенности реализации CPython:** Дескрипторы членов – это атрибуты, определённые в модулях расширения через структуры [`PyMemberDef`](https://python-all.ru/2.7/c-api/structures.html#c.PyMemberDef). В реализациях Python без таких типов этот метод всегда возвращает `False`.186187Новое в версии 2.5.188189## 28.13.2. Получение исходного кода190191#### `inspect.getdoc(object)`192193Получить строку документации для объекта, очищенную с помощью [`cleandoc()`](https://python-all.ru/2.7/library/inspect.html#inspect.cleandoc).194195#### `inspect.getcomments(object)`196197Возвращает единой строкой все строки комментариев, непосредственно предшествующие исходному коду объекта (для класса, функции или метода) или находящиеся в начале исходного файла Python (если объект – модуль).198199#### `inspect.getfile(object)`200201Возвращает имя (текстового или бинарного) файла, в котором определён объект. Вызывает исключение [`TypeError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.TypeError), если объект – встроенный модуль, класс или функция.202203#### `inspect.getmodule(object)`204205Пытается определить модуль, в котором был определён объект.206207#### `inspect.getsourcefile(object)`208209Возвращает имя файла исходного кода Python, в котором был определён объект. Вызовет исключение [`TypeError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.TypeError), если объект является встроенным модулем, классом или функцией.210211#### `inspect.getsourcelines(object)`212213Возвращает список строк исходного кода и номер начальной строки для объекта. Аргументом может быть модуль, класс, метод, функция, объект трассировки, фрейм или объект кода. Исходный код возвращается в виде списка строк, соответствующих объекту, а номер строки указывает, где в исходном файле находится первая строка кода. Если исходный код не удаётся получить, возбуждается исключение [`IOError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.IOError).214215#### `inspect.getsource(object)`216217Возвращает текст исходного кода для объекта. Аргументом может быть модуль, класс, метод, функция, объект трассировки, фрейм или объект кода. Исходный код возвращается в виде одной строки. Если исходный код не удаётся получить, возбуждается исключение [`IOError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.IOError).218219#### `inspect.cleandoc(doc)`220221Убирает отступы из docstrings, которые выровнены с блоками кода.222223Из первой строки удаляются все начальные пробелы. Все начальные пробелы, которые можно равномерно удалить со второй строки и далее, также удаляются. Пустые строки в начале и конце удаляются. Кроме того, все табуляции заменяются пробелами.224225Новое в версии 2.6.226227## 28.13.3. Классы и функции228229#### `inspect.getclasstree(classes[, unique])`230231Упорядочивает заданный список классов в иерархию вложенных списков. Если встречается вложенный список, он содержит классы, унаследованные от класса, запись которого непосредственно предшествует этому списку. Каждая запись представляет собой кортеж из двух элементов, содержащий класс и кортеж его базовых классов. Если аргумент *unique* равен true, в возвращаемой структуре появляется ровно одна запись для каждого класса из заданного списка. В противном случае классы, использующие множественное наследование, и их потомки будут появляться несколько раз.232233#### `inspect.getargspec(func)`234235Получить имена и значения по умолчанию аргументов функции Python. Возвращается кортеж из четырёх элементов: `(args, varargs, keywords, defaults)`. *args* – это список имён аргументов (может содержать вложенные списки). *varargs* и *keywords* – это имена аргументов `*` и `**` или `None`. *defaults* – это кортеж значений аргументов по умолчанию или `None`, если аргументов по умолчанию нет; если этот кортеж содержит *n* элементов, они соответствуют последним *n* элементам, перечисленным в *args*.236237Изменено в версии 2.6: Возвращает [именованный кортеж](https://python-all.ru/2.7/glossary.html#term-named-tuple) `ArgSpec(args, varargs, keywords, defaults)`.238239#### `inspect.getargvalues(frame)`240241Получить информацию об аргументах, переданных в определённый фрейм. Возвращается кортеж из четырёх элементов: `(args, varargs, keywords, locals)`. *args* – это список имён аргументов (может содержать вложенные списки). *varargs* и *keywords* – это имена аргументов `*` и `**` или `None`. *locals* – это словарь локальных переменных данного фрейма.242243Изменено в версии 2.6: Возвращает [именованный кортеж](https://python-all.ru/2.7/glossary.html#term-named-tuple) `ArgInfo(args, varargs, keywords, locals)`.244245#### `inspect.formatargspec(args[, varargs, varkw, defaults, formatarg, formatvarargs, formatvarkw, formatvalue, join])`246247Форматирует красивое описание аргументов из четырёх значений, возвращаемых [`getargspec()`](https://python-all.ru/2.7/library/inspect.html#inspect.getargspec). Аргументы format\* – это соответствующие опциональные функции форматирования, которые вызываются для преобразования имён и значений в строки.248249#### `inspect.formatargvalues(args[, varargs, varkw, locals, formatarg, formatvarargs, formatvarkw, formatvalue, join])`250251Форматирует красивое описание аргументов из четырёх значений, возвращаемых [`getargvalues()`](https://python-all.ru/2.7/library/inspect.html#inspect.getargvalues). Аргументы format\* – это соответствующие опциональные функции форматирования, которые вызываются для преобразования имён и значений в строки.252253#### `inspect.getmro(cls)`254255Возвращает кортеж базовых классов класса cls, включая cls, в порядке разрешения методов (MRO). Ни один класс не встречается в этом кортеже более одного раза. Обратите внимание, что порядок разрешения методов зависит от типа cls. Если не используется особенная пользовательская метатипизация, cls будет первым элементом кортежа.256257#### `inspect.getcallargs(func[, *args][, **kwds])`258259Связывает *args* и *kwds* с именами аргументов функции или метода Python *func*, как если бы она была вызвана с ними. Для связанных методов (bound methods) также связывает первый аргумент (обычно названный `self`) с соответствующим экземпляром. Возвращается словарь, отображающий имена аргументов (включая имена аргументов `*` и `**`, если они есть) на их значения из *args* и *kwds*. В случае неправильного вызова *func*, т.е. когда `func(*args, **kwds)` возбудило бы исключение из-за несовместимой сигнатуры, возбуждается исключение того же типа и с тем же или похожим сообщением. Например:260261```python262>>> from inspect import getcallargs263>>> def f(a, b=1, *pos, **named):264...     pass265>>> getcallargs(f, 1, 2, 3)266{'a': 1, 'named': {}, 'b': 2, 'pos': (3,)}267>>> getcallargs(f, a=2, x=4)268{'a': 2, 'named': {'x': 4}, 'b': 1, 'pos': ()}269>>> getcallargs(f)270Traceback (most recent call last):271...272TypeError: f() takes at least 1 argument (0 given)273```274275Новое в версии 2.7.276277## 28.13.4. Стек интерпретатора278279Когда следующие функции возвращают «записи фреймов» (frame records), каждая запись представляет собой кортеж из шести элементов: объект фрейма, имя файла, номер текущей строки, имя функции, список строк контекста из исходного кода и индекс текущей строки в этом списке.280281> **Примечание**282>283> Хранение ссылок на объекты фреймов (как в первом элементе записей фреймов, возвращаемых этими функциями) может привести к созданию циклических ссылок в программе. После создания циклической ссылки время жизни всех объектов, доступных из объектов, образующих цикл, может значительно увеличиться, даже если включён дополнительный детектор циклов Python. Если такие циклы необходимо создать, важно убедиться, что они явно разрываются, чтобы избежать задержки уничтожения объектов и увеличения потребления памяти.284>285> Хотя детектор циклов поймает их, уничтожение фреймов (и локальных переменных) можно сделать детерминированным, удалив цикл в предложении [`finally`](https://python-all.ru/2.7/reference/compound_stmts.html#finally). Это также важно, если детектор циклов был отключён при компиляции Python или с помощью [`gc.disable()`](https://python-all.ru/2.7/library/gc.html#gc.disable). Например:286>287> ```python288> def handle_stackframe_without_leak():289>     frame = inspect.currentframe()290>     try:291>         # Выполнить действие с фреймом292>     finally:293>         del frame294> ```295296Необязательный аргумент *context*, поддерживаемый большинством этих функций, задаёт количество возвращаемых строк контекста, которые располагаются вокруг текущей строки.297298#### `inspect.getframeinfo(frame[, context])`299300Получить информацию об объекте фрейма или трассировки. Возвращается 5-кортеж, содержащий последние пять элементов записи фрейма.301302Изменено в версии 2.6: Возвращает [именованный кортеж](https://python-all.ru/2.7/glossary.html#term-named-tuple) `Traceback(filename, lineno, function, code_context, index)`.303304#### `inspect.getouterframes(frame[, context])`305306Возвращает список записей о фреймах для фрейма и всех внешних фреймов. Эти фреймы представляют вызовы, которые привели к созданию *frame*. Первый элемент возвращаемого списка представляет *frame*; последний элемент представляет самый внешний вызов в стеке *frame*.307308#### `inspect.getinnerframes(traceback[, context])`309310Возвращает список записей о фреймах для фрейма traceback и всех внутренних фреймов. Эти фреймы представляют вызовы, являющиеся следствием *frame*. Первый элемент списка представляет *traceback*; последний элемент представляет место, где было возбуждено исключение.311312#### `inspect.currentframe()`313314Возвращает объект фрейма для фрейма стека вызывающего.315316**Особенность реализации CPython:** Эта функция полагается на поддержку фреймов стека Python в интерпретаторе, которая не гарантируется во всех реализациях Python. Если запустить в реализации без поддержки фреймов стека Python, эта функция возвращает `None`.317318#### `inspect.stack([context])`319320Возвращает список записей о фреймах для стека вызывающего кода. Первый элемент возвращаемого списка представляет вызывающий код; последний элемент представляет самый внешний вызов в стеке.321322#### `inspect.trace([context])`323324Возвращает список записей о фреймах для стека между текущим фреймом и фреймом, в котором было возбуждено исключение, обрабатываемое в данный момент. Первый элемент списка представляет вызывающий код; последний элемент представляет место, где было возбуждено исключение.325