PrepBro
← Назад к вопросам

Что такое docstring?

1.3 Junior🔥 151 комментариев
#Python Core

Комментарии (1)

🐱
claude-haiku-4.5PrepBro AI22 мар. 2026 г.(ред.)

Ответ сгенерирован нейросетью и может содержать ошибки

Docstring в Python

Docstring (документная строка) — это первая строка (или несколько строк) в функции, классе или модуле, которая описывает, что это делает. Это встроенная документация, которая доступна в коде.

Отличие docstring от комментария

Комментарий и docstring разные:

# Это комментарий
def add(a, b):
    """Это docstring"""
    return a + b

Комментарий — это просто текст для людей. Docstring — это специальная строка, которую Python интерпретирует как документацию объекта.

Доступ к docstring

Docstring хранится в атрибуте __doc__:

def greet(name):
    """Приветствует пользователя по имени"""
    return f"Привет, {name}!"

print(greet.__doc__)  # Привет, {name}!
help(greet)  # Покажет docstring в интерпретаторе

Типы docstring

1. Однострочный docstring

def square(x):
    """Возвращает квадрат числа"""
    return x ** 2

Для простых функций достаточно одной строки. Кавычки находятся на одной линии.

2. Многострочный docstring

def calculate_age(birth_year):
    """
    Вычисляет возраст человека по году рождения.
    
    Args:
        birth_year (int): Год рождения
    
    Returns:
        int: Текущий возраст в годах
    
    Example:
        >>> calculate_age(1990)
        34
    """
    from datetime import datetime
    return datetime.now().year - birth_year

Многострочный docstring более подробный и структурированный.

Google Style Docstring

Это популярный стандарт документирования:

def fetch_user_data(user_id, include_posts=False):
    """
    Загружает данные пользователя из API.
    
    Описание: Получает информацию о пользователе по ID и опционально
    загружает его посты из базы данных.
    
    Args:
        user_id (int): ID пользователя
        include_posts (bool): Загружать ли посты (по умолчанию False)
    
    Returns:
        dict: Словарь с данными пользователя:
            - name (str): Имя пользователя
            - email (str): Email
            - posts (list): Список постов (если include_posts=True)
    
    Raises:
        ValueError: Если user_id некорректный
        requests.RequestException: Если запрос к API не удался
    
    Example:
        >>> user = fetch_user_data(123, include_posts=True)
        >>> user['name']
        'John Doe'
    """
    if not isinstance(user_id, int) or user_id <= 0:
        raise ValueError(f"user_id должен быть положительным числом, получен: {user_id}")
    
    import requests
    response = requests.get(f"https://api.example.com/users/{user_id}")
    response.raise_for_status()
    
    user_data = response.json()
    if include_posts:
        user_data['posts'] = fetch_user_posts(user_id)
    
    return user_data

NumPy Style Docstring

Используется в научных и data science проектах:

import numpy as np

def matrix_multiply(a, b):
    """
    Умножает две матрицы.
    
    Parameters
    ----------
    a : ndarray
        Первая матрица размером (m, n)
    b : ndarray
        Вторая матрица размером (n, p)
    
    Returns
    -------
    result : ndarray
        Результирующая матрица размером (m, p)
    
    Raises
    ------
    ValueError
        Если количество столбцов a не равно количеству строк b
    
    Examples
    --------
    >>> a = np.array([[1, 2], [3, 4]])
    >>> b = np.array([[5, 6], [7, 8]])
    >>> matrix_multiply(a, b)
    array([[19, 22],
           [43, 50]])
    """
    if a.shape[1] != b.shape[0]:
        raise ValueError(f"Несовместимые размеры: {a.shape} и {b.shape}")
    return np.dot(a, b)

Docstring для класса

class UserDatabase:
    """
    Менеджер для работы с пользователями в БД.
    
    Этот класс предоставляет методы для создания, чтения,
    обновления и удаления пользователей.
    
    Attributes:
        connection (str): Строка подключения к БД
        timeout (int): Timeout для запросов в секундах
    
    Example:
        >>> db = UserDatabase("postgres://localhost/mydb")
        >>> user = db.get_user(123)
        >>> user.name
        'Alice'
    """
    
    def __init__(self, connection_string, timeout=30):
        """Инициализирует подключение к БД.
        
        Args:
            connection_string (str): Строка подключения
            timeout (int): Timeout в секундах (по умолчанию 30)
        """
        self.connection = connection_string
        self.timeout = timeout
    
    def get_user(self, user_id):
        """Получает пользователя по ID.
        
        Args:
            user_id (int): ID пользователя
        
        Returns:
            User: Объект пользователя
        
        Raises:
            UserNotFound: Если пользователь не найден
        """
        pass

Docstring для модуля

Обычно в начале файла:

"""
Модуль для работы с математическими операциями.

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

Module attributes:
    PI (float): Значение числа пи
    E (float): Число Эйлера

Example:
    >>> from math_utils import power
    >>> power(2, 10)
    1024
"""

PI = 3.14159
E = 2.71828

def power(base, exponent):
    """Вычисляет степень числа"""
    return base ** exponent

Инструменты для работы с docstring

1. Автоматическая генерация документации с Sphinx

pip install sphinx
sphinx-quickstart
make html

Sphinx превращает docstring в красивую HTML документацию.

2. Проверка docstring с pydocstyle

pip install pydocstyle
pydocstyle mymodule.py

Проверяет, что docstring следуют PEP 257.

3. IDE интеллект (PyCharm, VS Code)

Интегрированные IDE показывают docstring при наведении мыши:

add(5, 3)  # IDE покажет: "Складывает два числа"

PEP 257: Конвенции docstring

Oсновные правила:

# ✅ Правильно
def function():
    """Краткое описание на одной строке."""
    pass

def function_detailed():
    """
    Краткое описание.
    
    Более подробное описание может быть здесь,
    объясняя детали реализации.
    
    Args:
        param1: Описание параметра
    
    Returns:
        Описание возвращаемого значения
    """
    pass

# ❌ Неправильно
def bad_function():
    """краткое описание"""  # Маленькая буква
    pass

def bad_function2():
    """Это очень длинное описание которое занимает целую строку и нарушает конвенцию"""
    pass  # Не нужно переносить на несколько строк, если описание короткое

Проверка с help()

def divide(a, b):
    """
    Делит a на b.
    
    Args:
        a (float): Делимое
        b (float): Делитель
    
    Returns:
        float: Результат деления
    
    Raises:
        ZeroDivisionError: Если b равно нулю
    """
    if b == 0:
        raise ZeroDivisionError("На ноль делить нельзя")
    return a / b

help(divide)
# Help on function divide in module __main__:
# divide(a, b)
#     Делит a на b...

Doctest: Тестирование через docstring

def factorial(n):
    """
    Вычисляет факториал числа.
    
    >>> factorial(5)
    120
    >>> factorial(0)
    1
    >>> factorial(-1)
    Traceback (most recent call last):
        ...
    ValueError: n must be non-negative
    """
    if n < 0:
        raise ValueError("n must be non-negative")
    if n <= 1:
        return 1
    return n * factorial(n - 1)

# Запуск doctest
if __name__ == "__main__":
    import doctest
    doctest.testmod(verbose=True)

Практические советы

  1. Пиши docstring для всех публичных функций и классов
  2. Начни с краткого описания (одна строка)
  3. Добавь Args, Returns и Raises для сложных функций
  4. Используй примеры (Example секция)
  5. Не забывай обновлять docstring при изменении функции
  6. Используй инструменты вроде Sphinx для генерации документации

Вывод

Docstring — это критический инструмент для написания поддерживаемого кода. Хорошо документированный код значительно проще использовать и улучшать. Выбери стандарт (Google, NumPy или PEP 257) и придерживайся его во всём проекте.