inspect.md

1> **Источник:** https://python-all.ru/3.1/library/inspect.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# 27.11. `inspect` – Инспекция работающих объектов89Модуль `inspect` предоставляет несколько полезных функций для получения информации о работающих объектах, таких как модули, классы, методы, функции, трассировки, объекты фреймов и объекты кода. Например, он может помочь изучить содержимое класса, получить исходный код метода, извлечь и отформатировать список аргументов функции или получить всю информацию, необходимую для отображения подробной трассировки.1011Этот модуль предоставляет четыре основных вида сервисов: проверка типов, получение исходного кода, инспекция классов и функций, а также анализ стека интерпретатора.1213## 27.11.1. Типы и члены1415Функция [`getmembers()`](https://python-all.ru/3.1/library/inspect.html#inspect.getmembers) извлекает члены объекта, такого как класс или модуль. Шестнадцать функций, имена которых начинаются с «is», в основном предоставляются как удобные варианты для второго аргумента [`getmembers()`](https://python-all.ru/3.1/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.1/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(object[, predicate])`6263Возвращает все члены объекта в виде списка пар (имя, значение), отсортированных по имени. Если передан необязательный аргумент *predicate*, включаются только те члены, для которых предикат возвращает истинное значение.6465> **Примечание**66>67> [`getmembers()`](https://python-all.ru/3.1/library/inspect.html#inspect.getmembers) не возвращает атрибуты метакласса, когда аргумент является классом (это поведение унаследовано от функции [`dir()`](https://python-all.ru/3.1/library/functions.html#dir)).6869#### `inspect.getmoduleinfo(path)`7071Возвращает7273[*именованный кортеж*](https://python-all.ru/3.1/glossary.html#term-named-tuple)7475`ModuleInfo(name, suffix, mode, module_type)`7677со значениями, описывающими, как Python будет интерпретировать файл по7879*path*8081, если это модуль, или8283`None`8485, если он не идентифицируется как модуль. В этом кортеже8687*name*8889– имя модуля без имени оборачивающего пакета,9091*suffix*9293– конечная часть имени файла (которая может быть не расширением, отделённым точкой),9495*mode*9697– режим9899[`open()`](https://python-all.ru/3.1/library/functions.html#open)100101, который будет использован (102103`'r'`104105или106107`'rb'`108109), а110111*module\_type*112113– целое число, представляющее тип модуля.114115*module\_type*116117будет иметь значение, которое можно сравнить с константами, определёнными в модуле118119[`imp`](https://python-all.ru/3.1/library/imp.html#module-imp)120121; подробнее о типах модулей см. документацию этого модуля.122123#### `inspect.getmodulename(path)`124125Возвращает имя модуля, задаваемое файлом126127*path*128129, без включения имён объемлющих пакетов. Используется тот же алгоритм, что и интерпретатор при поиске модулей. Если имя не удаётся сопоставить по правилам интерпретатора, возвращается130131`None`132133.134135#### `inspect.ismodule(object)`136137Возвращает True, если объект является модулем.138139#### `inspect.isclass(object)`140141Возвращает True, если объект является классом, встроенным или созданным в коде Python.142143#### `inspect.ismethod(object)`144145Возвращает True, если объект является связанным методом, написанным на Python.146147#### `inspect.isfunction(object)`148149Возвращает True, если объект является функцией Python, включая функции, созданные с помощью выражения150151[*lambda*](https://python-all.ru/3.1/glossary.html#term-lambda)152153.154155#### `inspect.isgeneratorfunction(object)`156157Возвращает True, если объект является функцией-генератором Python.158159#### `inspect.isgenerator(object)`160161Возвращает True, если объект является генератором.162163#### `inspect.istraceback(object)`164165Возвращает True, если объект является трассировкой.166167#### `inspect.isframe(object)`168169Возвращает True, если объект является фреймом.170171#### `inspect.iscode(object)`172173Возвращает True, если объект является кодом.174175#### `inspect.isbuiltin(object)`176177Возвращает True, если объект является встроенной функцией или связанным встроенным методом.178179#### `inspect.isroutine(object)`180181Возвращает True, если объект является пользовательской или встроенной функцией или методом.182183#### `inspect.isabstract(object)`184185Возвращает True, если объект является абстрактным базовым классом.186187#### `inspect.ismethoddescriptor(object)`188189Возвращает true, если объект является дескриптором метода, но не если [`ismethod()`](https://python-all.ru/3.1/library/inspect.html#inspect.ismethod), [`isclass()`](https://python-all.ru/3.1/library/inspect.html#inspect.isclass), [`isfunction()`](https://python-all.ru/3.1/library/inspect.html#inspect.isfunction) или [`isbuiltin()`](https://python-all.ru/3.1/library/inspect.html#inspect.isbuiltin) возвращают true.190191Это, например, верно для `int.__add__`. Объект, проходящий эту проверку, имеет атрибут `__get__`, но не имеет атрибута `__set__`, а кроме того, набор атрибутов различается. `__name__` обычно осмысленно, и `__doc__` часто тоже.192193Методы, реализованные через дескрипторы и также проходящие один из других тестов, возвращают false для теста [`ismethoddescriptor()`](https://python-all.ru/3.1/library/inspect.html#inspect.ismethoddescriptor) просто потому, что другие тесты обещают больше – например, можно рассчитывать на наличие атрибута `__func__` (и т.д.), когда объект проходит [`ismethod()`](https://python-all.ru/3.1/library/inspect.html#inspect.ismethod).194195#### `inspect.isdatadescriptor(object)`196197Возвращает True, если объект является дескриптором данных.198199Дескрипторы данных имеют как атрибут `__get__`, так и атрибут `__set__`. Примеры: свойства (определённые в Python), getsets и элементы. Последние два определены на C, и для этих типов существуют более специфичные проверки, которые работают во всех реализациях Python. Обычно дескрипторы данных также имеют атрибуты `__name__` и `__doc__` (свойства, getsets и элементы имеют оба этих атрибута), но это не гарантируется.200201#### `inspect.isgetsetdescriptor(object)`202203Возвращает True, если объект является дескриптором getset.204205**Особенности реализации CPython:** getsets – это атрибуты, определённые в модулях расширения через структуры `PyGetSetDef`. Для реализаций Python без таких типов этот метод всегда возвращает `False`.206207#### `inspect.ismemberdescriptor(object)`208209Возвращает True, если объект является дескриптором члена.210211**Особенность реализации CPython:** Дескрипторы членов – это атрибуты, определяемые в модулях расширения через структуры [`PyMemberDef`](https://python-all.ru/3.1/c-api/structures.html#PyMemberDef). Для реализаций Python без таких типов этот метод всегда возвращает `False`.212213## 27.11.2. Извлечение исходного кода214215#### `inspect.getdoc(object)`216217Возвращает строку документации объекта, очищенную с помощью218219[`cleandoc()`](https://python-all.ru/3.1/library/inspect.html#inspect.cleandoc)220221.222223#### `inspect.getcomments(object)`224225Возвращает единой строкой все строки комментариев, непосредственно предшествующие исходному коду объекта (для класса, функции или метода) или находящиеся в начале исходного файла Python (если объект – модуль).226227#### `inspect.getfile(object)`228229Возвращает имя (текстового или бинарного) файла, в котором определён объект. Это вызовет230231[`TypeError`](https://python-all.ru/3.1/library/exceptions.html#TypeError)232233, если объект является встроенным модулем, классом или функцией.234235#### `inspect.getmodule(object)`236237Пытается определить модуль, в котором был определён объект.238239#### `inspect.getsourcefile(object)`240241Возвращает имя исходного файла Python, в котором определён объект. Это вызовет242243[`TypeError`](https://python-all.ru/3.1/library/exceptions.html#TypeError)244245, если объект является встроенным модулем, классом или функцией.246247#### `inspect.getsourcelines(object)`248249Возвращает список строк исходного кода и номер начальной строки для объекта. Аргументом может быть модуль, класс, метод, функция, трассировка, фрейм или объект кода. Исходный код возвращается в виде списка строк, соответствующих объекту, а номер строки указывает, где в исходном файле была найдена первая строка кода. Возбуждается исключение250251[`IOError`](https://python-all.ru/3.1/library/exceptions.html#IOError)252253, если исходный код не удается получить.254255#### `inspect.getsource(object)`256257Возвращает текст исходного кода для объекта. Аргументом может быть модуль, класс, метод, функция, трассировка, фрейм или объект кода. Исходный код возвращается в виде одной строки. Возбуждается исключение258259[`IOError`](https://python-all.ru/3.1/library/exceptions.html#IOError)260261, если исходный код не удается получить.262263#### `inspect.cleandoc(doc)`264265Убирает отступы из строк документации, которые добавлены для выравнивания с блоками кода. Удаляются все пробельные символы, которые можно равномерно убрать, начиная со второй строки. Также все табуляции заменяются пробелами.266267## 27.11.3. Классы и функции268269#### `inspect.getclasstree(classes, unique=False)`270271Упорядочивает заданный список классов в иерархию вложенных списков. Если встречается вложенный список, он содержит классы, унаследованные от класса, запись которого непосредственно предшествует этому списку. Каждая запись представляет собой кортеж из двух элементов, содержащий класс и кортеж его базовых классов. Если аргумент272273*unique*274275равен true, в возвращаемой структуре появляется ровно одна запись для каждого класса из заданного списка. В противном случае классы, использующие множественное наследование, и их потомки будут появляться несколько раз.276277#### `inspect.getargspec(func)`278279Получает имена и значения по умолчанию аргументов функции Python. Возвращается [*именованный кортеж*](https://python-all.ru/3.1/glossary.html#term-named-tuple) `ArgSpec(args, varargs, keywords, defaults)`. *args* – это список имен аргументов. *varargs* и *keywords* – имена аргументов `*` и `**` или `None`. *defaults* – это кортеж значений аргументов по умолчанию или None, если аргументов по умолчанию нет; если этот кортеж содержит *n* элементов, они соответствуют последним *n* элементам, перечисленным в *args*.280281Устарело с версии 3.0: Вместо этого используйте [`getfullargspec()`](https://python-all.ru/3.1/library/inspect.html#inspect.getfullargspec), который предоставляет информацию об именованных аргументах (keyword-only) и аннотациях.282283#### `inspect.getfullargspec(func)`284285Возвращает имена и значения по умолчанию аргументов функции Python. Возвращается [*именованный кортеж*](https://python-all.ru/3.1/glossary.html#term-named-tuple):286287`FullArgSpec(args, varargs, varkw, defaults, kwonlyargs, kwonlydefaults, annotations)`288289*args* – список имён аргументов. *varargs* и *varkw* – имена аргументов `*` и `**` или `None`. *defaults* – n-кортеж значений по умолчанию для последних n аргументов. *kwonlyargs* – список имён только ключевых аргументов. *kwonlydefaults* – словарь, сопоставляющий имена из kwonlyargs значениям по умолчанию. *annotations* – словарь, сопоставляющий имена аргументов аннотациям.290291Первые четыре элемента в кортеже соответствуют [`getargspec()`](https://python-all.ru/3.1/library/inspect.html#inspect.getargspec).292293#### `inspect.getargvalues(frame)`294295Получает информацию об аргументах, переданных в конкретный фрейм. Возвращается296297[*именованный кортеж*](https://python-all.ru/3.1/glossary.html#term-named-tuple)298299`ArgInfo(args, varargs, keywords, locals)`300301.302303*args*304305– список имён аргументов.306307*varargs*308309и310311*keywords*312313– имена аргументов314315`*`316317и318319`**`320321или322323`None`324325.326327*locals*328329– словарь локальных переменных данного фрейма.330331#### `inspect.formatargspec(args[, varargs, varkw, defaults, formatarg, formatvarargs, formatvarkw, formatvalue])`332333Форматирует читаемое описание аргументов из четырёх значений, возвращаемых334335[`getargspec()`](https://python-all.ru/3.1/library/inspect.html#inspect.getargspec)336337. Аргументы format\* – это соответствующие необязательные функции форматирования, которые вызываются для преобразования имён и значений в строки.338339#### `inspect.formatargvalues(args[, varargs, varkw, locals, formatarg, formatvarargs, formatvarkw, formatvalue])`340341Форматирует красивое описание аргументов из четырёх значений, возвращаемых342343[`getargvalues()`](https://python-all.ru/3.1/library/inspect.html#inspect.getargvalues)344345. Аргументы format\* – это соответствующие необязательные функции форматирования, которые вызываются для преобразования имён и значений в строки.346347#### `inspect.getmro(cls)`348349Возвращает кортеж базовых классов класса cls, включая cls, в порядке разрешения методов (MRO). Ни один класс не встречается в этом кортеже более одного раза. Обратите внимание, что порядок разрешения методов зависит от типа cls. Если не используется особенная пользовательская метатипизация, cls будет первым элементом кортежа.350351## 27.11.4. Стек интерпретатора352353Когда следующие функции возвращают «записи фреймов» (frame records), каждая запись представляет собой кортеж из шести элементов: объект фрейма, имя файла, номер текущей строки, имя функции, список строк контекста из исходного кода и индекс текущей строки в этом списке.354355> **Примечание**356>357> Хранение ссылок на объекты фреймов (как в первом элементе записей фреймов, возвращаемых этими функциями) может привести к созданию циклических ссылок в программе. После создания циклической ссылки время жизни всех объектов, доступных из объектов, образующих цикл, может значительно увеличиться, даже если включён дополнительный детектор циклов Python. Если такие циклы необходимо создать, важно убедиться, что они явно разрываются, чтобы избежать задержки уничтожения объектов и увеличения потребления памяти.358>359> Хотя детектор циклов перехватит их, уничтожение фреймов (и локальных переменных) можно сделать детерминированным, удалив цикл в блоке [`finally`](https://python-all.ru/3.1/reference/compound_stmts.html#finally). Это также важно, если детектор циклов был отключён при компиляции Python или с помощью [`gc.disable()`](https://python-all.ru/3.1/library/gc.html#gc.disable). Например:360>361> ```python362> def handle_stackframe_without_leak():363>     frame = inspect.currentframe()364>     try:365>         # Выполнить действие с фреймом366>     finally:367>         del frame368> ```369370Необязательный аргумент *context*, поддерживаемый большинством этих функций, задаёт количество возвращаемых строк контекста, которые располагаются вокруг текущей строки.371372#### `inspect.getframeinfo(frame, context=1)`373374Возвращает информацию об объекте фрейма или traceback. Возвращается375376[*именованный кортеж*](https://python-all.ru/3.1/glossary.html#term-named-tuple)377378`Traceback(filename, lineno, function, code_context, index)`379380.381382#### `inspect.getouterframes(frame, context=1)`383384Возвращает список записей фреймов для фрейма и всех внешних фреймов. Эти фреймы представляют вызовы, которые привели к созданию385386*frame*387388. Первая запись в возвращаемом списке представляет389390*frame*391392; последняя запись представляет самый внешний вызов в стеке393394*frame*395396.397398#### `inspect.getinnerframes(traceback, context=1)`399400Возвращает список записей о фреймах для фрейма traceback и всех внутренних фреймов. Эти фреймы представляют вызовы, являющиеся следствием401402*frame*403404. Первый элемент списка представляет405406*traceback*407408; последний элемент представляет место, где было возбуждено исключение.409410#### `inspect.currentframe()`411412Возвращает объект фрейма для фрейма стека вызывающего.413414**Особенность реализации CPython:** Эта функция полагается на поддержку стековых фреймов Python в интерпретаторе, которая не гарантируется во всех реализациях Python. Если запуск происходит в реализации без поддержки стековых фреймов Python, эта функция возвращает `None`.415416#### `inspect.stack(context=1)`417418Возвращает список записей о фреймах для стека вызывающего кода. Первый элемент возвращаемого списка представляет вызывающий код; последний элемент представляет самый внешний вызов в стеке.419420#### `inspect.trace(context=1)`421422Возвращает список записей о фреймах для стека между текущим фреймом и фреймом, в котором было возбуждено исключение, обрабатываемое в данный момент. Первый элемент списка представляет вызывающий код; последний элемент представляет место, где было возбуждено исключение.423