Как получить docstring из функции в Python?

Как получить docstring из функции в Python

Docstring — это строка документации, которая описывает функцию, класс или модуль. Python предоставляет несколько способов доступа к ней. Это важно для создания self-documenting кода и инструментов анализа.

1. Основной способ: атрибут doc

Каждый объект в Python имеет атрибут __doc__, содержащий его docstring:

def greet(name: str) -> str:
    """Приветствует пользователя по имени.
    
    Args:
        name: Имя пользователя
    
    Returns:
        Приветственное сообщение
    """
    return f"Hello, {name}!"

# Получить docstring
print(greet.__doc__)
# Приветствует пользователя по имени.
#
# Args:
#     name: Имя пользователя
#
# Returns:
#     Приветственное сообщение

2. Функция help()

Встроенная функция help() форматирует и выводит docstring:

help(greet)

# Выведет:
# Help on function greet in module __main__:
#
# greet(name: str) -> str
#     Приветствует пользователя по имени.
#     ...

3. Функция inspect.getdoc()

Для получения очищенного docstring используй модуль inspect:

import inspect

def my_function():
    """  
    Функция с отступами.
    Вторая строка.
    """
    pass

# __doc__ содержит отступы и пробелы
print(repr(my_function.__doc__))
# '  \n    Функция с отступами.\n    Вторая строка.\n    '

# inspect.getdoc() убирает отступы
print(inspect.getdoc(my_function))
# Функция с отступами.
# Вторая строка.

4. Docstring для классов и методов

class Calculator:
    """Калькулятор для базовых операций."""
    
    def add(self, a, b):
        """Суммирует два числа."""
        return a + b
    
    def multiply(self, a, b):
        """Умножает два числа."""
        return a * b

# Docstring класса
print(Calculator.__doc__)  # Калькулятор для базовых операций.

# Docstring метода
print(Calculator.add.__doc__)  # Суммирует два числа.

# Через экземпляр
calc = Calculator()
print(calc.add.__doc__)  # Суммирует два числа.

5. Docstring для модулей

# my_module.py
"""Модуль для работы с данными.

Содержит функции обработки CSV и JSON файлов.
"""

import my_module
print(my_module.__doc__)  # Модуль для работы с данными...

6. Форматы docstring

Google Style (популярный):

def process_data(items: list, sort: bool = False) -> dict:
    """Обрабатывает список элементов.
    
    Args:
        items: Список элементов для обработки
        sort: Сортировать ли элементы. Defaults to False.
    
    Returns:
        Словарь с обработанными данными
    
    Raises:
        ValueError: Если items пусто
    """
    if not items:
        raise ValueError("items не может быть пусто")
    return {"data": items, "sorted": sort}

NumPy/SciPy Style:

def calculate(x, y):
    """Вычисляет сумму двух чисел.
    
    Parameters
    ----------
    x : float
        Первое число
    y : float
        Второе число
    
    Returns
    -------
    float
        Сумма x и y
    """
    return x + y

reStructuredText (Sphinx):

def fetch_data(url: str) -> str:
    """Получает данные с URL.
    
    :param url: Адрес ресурса
    :type url: str
    :returns: Данные с сервера
    :rtype: str
    :raises requests.RequestException: Если не удалось подключиться
    """
    import requests
    return requests.get(url).text

7. Практические примеры

Автоматическое создание документации:

import inspect

def generate_docs(module):
    """Генерирует документацию модуля."""
    print(f"# {module.__name__}\n")
    print(module.__doc__ or "No module docstring")
    print("\n## Functions\n")
    
    for name, obj in inspect.getmembers(module, inspect.isfunction):
        if not name.startswith('_'):
            doc = inspect.getdoc(obj) or "No docstring"
            print(f"### {name}\n\n{doc}\n")

# Использование
import my_module
generate_docs(my_module)

Валидация docstring в тестах:

import inspect

def test_all_functions_have_docstring():
    """Проверяет, что все функции имеют docstring."""
    import my_module
    
    for name, func in inspect.getmembers(my_module, inspect.isfunction):
        if not name.startswith('_'):
            assert func.__doc__, f"Function {name} has no docstring"
            assert len(func.__doc__) > 20, f"Docstring {name} too short"

Декоратор для проверки docstring:

def require_docstring(func):
    """Декоратор: требует docstring у функции."""
    if not func.__doc__:
        raise ValueError(f"Function {func.__name__} must have a docstring")
    return func

@require_docstring
def my_function():
    """Функция с документацией."""
    pass

# Это вызовет ошибку:
# @require_docstring
# def bad_function():
#     pass

8. Отсутствие docstring

def no_doc():
    pass

print(no_doc.__doc__)  # None

if no_doc.__doc__ is None:
    print("Функция не имеет docstring")

9. Динамическое изменение docstring

def my_func():
    """Оригинальный docstring."""
    pass

# Можно изменить docstring
my_func.__doc__ = "Новый docstring"
print(my_func.__doc__)  # Новый docstring

Вывод

• Используй __doc__ для получения docstring программно
• Используй help() для интерактивной справки
• Используй inspect.getdoc() для очищенного текста
• Пиши docstring для всех публичных функций и классов
• Выбери один стиль (Google Style рекомендуется для читаемости)
• Проверяй наличие docstring в тестах