Inspect.getdoc: примеры (PYTHON)

Простые примеры использования

Пример получения docstring из функции.

import inspect
def example_func():
    """Это документация для example_func.
    
    Она может содержать несколько строк.
    """
    pass

print(inspect.getdoc(example_func))

Это документация для example_func.

Она может содержать несколько строк.

Пример с классом и наследованием.

import inspect

class Parent:
    """Документация родительского класса."""
    pass

class Child(Parent):
    pass

print(inspect.getdoc(Child))

Документация родительского класса.

Работа с объектами, у которых нет docstring.

import inspect
import math

# Встроенная функция без docstring (на самом деле он есть, но на английском)
print(inspect.getdoc(math.sqrt) is not None)
# Объект без документации
print(inspect.getdoc(123))

True
None

Похожие функции в Python

Для интроспекции документации в Python также доступны несколько других средств.

1. Прямой доступ к атрибуту __doc__: Любой объект может иметь атрибут __doc__, содержащий сырую, неочищенную строку документации. В отличие от inspect.getdoc, он не выполняет очистку отступов и не ищет docstring в родительских классах.

def my_func():
    """    Документация с отступом."""
    pass

print(repr(my_func.__doc__))
print(repr(inspect.getdoc(my_func)))

'    Документация с отступом.'
'Документация с отступом.'

2. Функция inspect.getcomments(object): Возвращает строку комментариев, находящихся непосредственно перед исходным кодом объекта, а не его docstring. Полезно для получения неформальных комментариев.

3. Функция inspect.cleandoc(docstring): Функция нижнего уровня, которую использует getdoc для очистки docstring. Ее применяют напрямую, если уже есть сырая строка документации.

Выбор инструмента: inspect.getdoc предпочтительнее для получения готовой к отображению документации объекта с учетом наследования. Прямой доступ к __doc__ используют, когда нужен оригинальный, необработанный текст. inspect.getcomments служит для иных целей - получения блока комментариев.

Аналоги в других языках программирования

JavaScript: В JavaScript нет прямого встроенного аналога. Для функций можно использовать свойство .toString(), которое вернет исходный код, включающий комментарии. Многие инструменты (например, JSDoc) парсят комментарии специального формата.

// Пример с Node.js (CommonJS)
function example() {
    /**
     * Это документация JSDoc.
     */
}
console.log(example.toString());

function example() {
    /**
     * Это документация JSDoc.
     */
}

Java: Для получения Javadoc во время выполнения требуется использование инструментов рефлексии и часто дополнительных библиотек, так как Javadoc обычно не сохраняется в скомпилированном .class файле. Аннотации можно получить через Reflection API.

// Псевдокод, так как получение Javadoc нетривиально
Method method = MyClass.class.getMethod("myMethod");
// Прямого способа получить Javadoc нет

PHP: Функция ReflectionClass::getDocComment() или ReflectionFunction::getDocComment() возвращает блок комментариев DocBlock.

/**
 * Это документация класса.
 */
class MyClass {}

$reflection = new ReflectionClass('MyClass');
echo $reflection->getDocComment();

/**
 * Это документация класса.
 */

C#: XML-документационные комментарии могут быть получены через рефлексию, если сборка скомпилирована с поддержкой документации (/doc). Обычно комментарии находятся в отдельном .xml файле и загружаются отдельно.

Golang: Пакет go/doc предоставляет средства для извлечения и обработки документации из исходного кода Go. Документация тесно связана с исходниками и парсится из них.

Kotlin: Функция KFunction.docString из библиотеки рефлексии kotlin-reflect позволяет получить docstring функции Kotlin.

Главное отличие Python-функции inspect.getdoc - ее простота и доступность непосредственно из стандартной библиотеки для любого объекта во время выполнения, включая встроенные, с автоматической очисткой текста.

Типичные ошибки

Ошибки при работе с inspect.getdoc чаще связаны с непониманием ее поведения, а не с исключениями времени выполнения.

1. Ожидание документации там, где ее нет. Функция возвращает None для объектов без docstring, что иногда приводит к ошибкам при попытке выполнить строковые операции.

import inspect
result = inspect.getdoc(int)
# Неправильно: print(result.upper())
# Правильно:
if result:
    print(result.upper())
else:
    print("Документация не найдена")

Документация не найдена

2. Передача экземпляра вместо класса или функции. Функция ищет docstring у типа объекта, а не у самого экземпляра (если только экземпляр не имеет собственного __doc__).

import inspect

class MyClass:
    """Документация класса."""
    pass

obj = MyClass()
print(inspect.getdoc(obj))  # Получит docstring класса
print(inspect.getdoc(MyClass))  # То же самое

Документация класса.
Документация класса.

3. Путаница между inspect.getdoc и inspect.getcomments. Эти функции возвращают разную информацию.

import inspect

# Комментарий перед функцией

def my_func():
    """Настоящий docstring."""
    pass

print("getdoc:", inspect.getdoc(my_func))
print("getcomments:", inspect.getcomments(my_func))

getdoc: Настоящий docstring.
getcomments: # Комментарий перед функцией

История изменений

Функция inspect.getdoc присутствует в Python уже долгое время и является стабильной. Существенных изменений в ее поведении или интерфейсе в последних основных версиях Python (3.x) не происходило.

Важным аспектом является то, что ее внутренняя реализация использует функцию inspect.cleandoc для очистки docstring. Сама логика очистки (удаление общих ведущих пробелов) остается неизменной.

Версия Python 3.5 принесла улучшения в модуль inspect в целом, но не затронула специфически getdoc. При работе с новыми версиями языка можно быть уверенным в обратной совместимости этой функции.

Расширенные примеры применения

Пример использования в инструменте для автоматического просмотра документации модуля.

import inspect
import os

def module_doc_overview(module):
    """Выводит имена и краткую документацию всех публичных объектов модуля."""
    print(f"Документация модуля {module.__name__}:\n")
    mod_doc = inspect.getdoc(module)
    if mod_doc:
        print(f"Модуль: {mod_doc[:100]}...\n")
    
    for name in dir(module):
        if not name.startswith('_'):
            obj = getattr(module, name)
            obj_doc = inspect.getdoc(obj)
            if obj_doc:
                first_line = obj_doc.split('\n')[0]
                print(f"{name}: {first_line[:80]}")

# module_doc_overview(os)  # Раскомментировать для запуска (вывод будет большим)

# Вывод будет содержать список объектов модуля os и первую строку их docstring.

Пример сравнения документации метода в иерархии классов.

import inspect

class A:
    def method(self):
        """Документация из класса A."""
        pass

class B(A):
    def method(self):
        """Документация из класса B."""
        pass

class C(A):
    pass

for cls in [A, B, C]:
    doc = inspect.getdoc(cls.method)
    print(f"{cls.__name__}.method: {doc}")

A.method: Документация из класса A.
B.method: Документация из класса B.
C.method: Документация из класса A.

Использование с декораторами, которые могут изменять или заменять docstring.

import inspect
from functools import wraps

def add_author(author):
    def decorator(func):
        original_doc = inspect.getdoc(func) or ""
        new_doc = f"Автор: {author}\n\n{original_doc}"
        @wraps(func)
        def wrapper(*args, **kwargs):
            return func(*args, **kwargs)
        wrapper.__doc__ = new_doc
        return wrapper
    return decorator

@add_author("Иван Петров")
def calculate():
    """Выполняет сложные вычисления."""
    return 42

print(inspect.getdoc(calculate))

Автор: Иван Петров

Выполняет сложные вычисления.

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

import inspect
print(inspect.getdoc(len))

Return the number of items in a container.