28.13. inspect – Инспекция активных объектов¶inspect – Inspect live objects

28.13.1. Типы и члены¶Types and members

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

Примечание:

1. Изменено в версии 2.2: im_class ранее ссылался на класс, который определил метод.

inspect.getmembers(object[, predicate])¶

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

Примечание

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

inspect.getmoduleinfo(path)¶

Возвращает кортеж значений, описывающих, как Python будет интерпретировать файл идентифицируемый путь, если это модуль, или None, если он не будет идентифицирован как модуль. Возвращаемый кортеж – (name, suffix, mode, module_type), где name – имя модуля без имени какого-либо включающего пакета, suffix – завершающая часть имени файла (которая может не быть расширением, отделённым точкой), mode – режим open(), который будет использован ('r' или 'rb'), а module_type – целое число, задающее тип модуля. module_type будет иметь значение, которое можно сравнить с константами, определёнными в модуле imp; см. документацию этого модуля для получения дополнительной информации о типах модулей.

Изменено в версии 2.6: Возвращает именованный кортеж ModuleInfo(name, suffix, mode, module_type).

inspect.getmodulename(path)¶

Возвращает имя модуля, заданного файлом путь, без включения имён включающих пакетов. При этом используется тот же алгоритм, что и интерпретатор использует при поиске модулей. Если имя не может быть сопоставлено согласно правилам интерпретатора, возвращается None.

inspect.ismodule(object)¶

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

inspect.isclass(object)¶

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

inspect.ismethod(object)¶

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

inspect.isfunction(object)¶

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

inspect.isgeneratorfunction(object)¶

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

Новое в версии 2.6.

inspect.isgenerator(object)¶

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

Новое в версии 2.6.

inspect.istraceback(object)¶

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

inspect.isframe(object)¶

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

inspect.iscode(object)¶

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

inspect.isbuiltin(object)¶

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

inspect.isroutine(object)¶

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

inspect.isabstract(object)¶

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

Новое в версии 2.6.

inspect.ismethoddescriptor(object)¶

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

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

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

inspect.isdatadescriptor(object)¶

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

Дескрипторы данных имеют оба метода – __get__ и __set__. Примерами являются свойства (определённые в Python), getsets и members. Последние два определены в C, и для этих типов существуют более специальные проверки, что надёжно во всех реализациях Python. Обычно дескрипторы данных также имеют атрибуты __name__ и __doc__ (свойства, getsets и members имеют оба этих атрибута), но это не гарантируется.

Новое в версии 2.3.

inspect.isgetsetdescriptor(object)¶

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

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

Новое в версии 2.5.

inspect.ismemberdescriptor(object)¶

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

Особенности реализации CPython: Дескрипторы членов – это атрибуты, определённые в модулях расширения через структуры PyMemberDef. В реализациях Python без таких типов этот метод всегда возвращает False.

Новое в версии 2.5.

28.13.2. Получение исходного кода¶Retrieving source code

inspect.getdoc(object)¶

Получить строку документации для объекта, очищенную с помощью cleandoc().

inspect.getcomments(object)¶

Возвращает единой строкой все строки комментариев, непосредственно предшествующие исходному коду объекта (для класса, функции или метода) или находящиеся в начале исходного файла Python (если объект – модуль).

inspect.getfile(object)¶

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

inspect.getmodule(object)¶

Пытается определить модуль, в котором был определён объект.

inspect.getsourcefile(object)¶

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

inspect.getsourcelines(object)¶

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

inspect.getsource(object)¶

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

inspect.cleandoc(doc)¶

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

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

Новое в версии 2.6.

28.13.3. Классы и функции¶Classes and functions

inspect.getclasstree(classes[, unique])¶

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

inspect.getargspec(func)¶

Получить имена и значения по умолчанию аргументов функции Python. Возвращается кортеж из четырёх элементов: (args, varargs, keywords, defaults). args – это список имён аргументов (может содержать вложенные списки). varargs и keywords – это имена аргументов * и ** или None. defaults – это кортеж значений аргументов по умолчанию или None, если аргументов по умолчанию нет; если этот кортеж содержит n элементов, они соответствуют последним n элементам, перечисленным в args.

Изменено в версии 2.6: Возвращает именованный кортеж ArgSpec(args, varargs, keywords, defaults).

inspect.getargvalues(frame)¶

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

Изменено в версии 2.6: Возвращает именованный кортеж ArgInfo(args, varargs, keywords, locals).

inspect.formatargspec(args[, varargs, varkw, defaults, formatarg, formatvarargs, formatvarkw, formatvalue, join])¶

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

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

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

inspect.getmro(cls)¶

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

inspect.getcallargs(func[, *args][, **kwds])¶

Связывает args и kwds с именами аргументов функции или метода Python func, как если бы она была вызвана с ними. Для связанных методов (bound methods) также связывает первый аргумент (обычно названный 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,)}
>>> getcallargs(f, a=2, x=4)
{'a': 2, 'named': {'x': 4}, 'b': 1, 'pos': ()}
>>> getcallargs(f)
Traceback (most recent call last):
...
TypeError: f() takes at least 1 argument (0 given)

Новое в версии 2.7.

28.13.4. Стек интерпретатора¶The interpreter stack

Когда следующие функции возвращают «записи фреймов» (frame records), каждая запись представляет собой кортеж из шести элементов: объект фрейма, имя файла, номер текущей строки, имя функции, список строк контекста из исходного кода и индекс текущей строки в этом списке.

def handle_stackframe_without_leak():
    frame = inspect.currentframe()
    try:
        # Выполнить действие с фреймом
    finally:
        del frame

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

inspect.getframeinfo(frame[, context])¶

Получить информацию об объекте фрейма или трассировки. Возвращается 5-кортеж, содержащий последние пять элементов записи фрейма.

Изменено в версии 2.6: Возвращает именованный кортеж Traceback(filename, lineno, function, code_context, index).

inspect.getouterframes(frame[, context])¶

Возвращает список записей о фреймах для фрейма и всех внешних фреймов. Эти фреймы представляют вызовы, которые привели к созданию frame. Первый элемент возвращаемого списка представляет frame; последний элемент представляет самый внешний вызов в стеке frame.

inspect.getinnerframes(traceback[, context])¶

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

inspect.currentframe()¶

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

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

inspect.stack([context])¶

Возвращает список записей о фреймах для стека вызывающего кода. Первый элемент возвращаемого списка представляет вызывающий код; последний элемент представляет самый внешний вызов в стеке.

inspect.trace([context])¶

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