inspect — Просмотр живых объектов

Исходный код: Lib/inspect.py

Модуль inspect предоставляет несколько полезных функций для получения информации о живых объектах, таких как модули, классы, методы, функции, трассировки, объекты фреймов и объекты кода. Например, он может помочь вам изучить содержимое класса, получить исходный код метода, извлечь и отформатировать список аргументов для функции или получить всю необходимую информацию для отображения подробной трассировки.

Этот модуль предоставляет четыре основных типа услуг: проверку типов, получение исходного кода, инспекцию классов и функций и изучение стека интерпретатора.

1. Типы и члены

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

Примечание:

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

inspect.getmembers(object[, predicate])

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

Примечание

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

inspect.getmoduleinfo(path)

Возвращает кортеж значений, которые описывают, как Python будет интерпретировать файл, указанный в path, если это модуль, или 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)

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

inspect.ismodule(object)

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

inspect.isclass(object)

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

inspect.ismethod(object)

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

inspect.isfunction(object)

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

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__ часто есть.

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

inspect.isdatadescriptor(object)

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

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

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

inspect.isgetsetdescriptor(object)

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

Деталь реализации CPython: getset — это атрибуты, определённые в модулях расширения с помощью структур PyGetSetDef. В реализациях Python без таких типов этот метод всегда возвращает False.

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

inspect.ismemberdescriptor(object)

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

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

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

2. Получение исходного кода

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)

Очищает отступы в строках документации, которые выровнены с блоками кода.

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

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

3. Классы и функции

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, в порядке разрешения методов. В этом кортеже каждый класс встречается не более одного раза. Обратите внимание, что порядок разрешения методов зависит от типа 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,)}
>>> 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.

4. Стек интерпретатора

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

def handle_stackframe_without_leak():
    frame = inspect.currentframe()
    try:
        # do something with the frame
    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])

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

inspect.currentframe()

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

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

inspect.stack([context])

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

inspect.trace([context])

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