Создавайте четкие и хорошо отформатированные строки документации Python за считанные секунды

Введение

«Я написал эту функцию 6 месяцев назад и теперь не могу вспомнить, что она делает!» Это звучит знакомо? В погоне за сроками мы часто упускаем из виду важность хорошей документации (или строк документации) для класса, методов и функций, которые мы создали.

Так что же такое строки документации?

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

def add_two_values(x:int, y:int = 0) -> int:
    """Add two values and return the sum.
    Args:
        x (int): first value
        y (int, optional): second value. Defaults to 0.
    Raises:
        TypeError: x and y must be integers
    Returns:
        int: summation of x and y
    """
    if not all([isinstance(i, int) for i in [x,y]]):
        raise TypeError('inputs must be integer')
    else:
        z = x + y
    return z

Строка документации выше содержит общее описание функции add_two_values, за которым следуют описания входных аргументов x и y , выходных данных z и возникших ошибок. Строки документации служат руководством для разработчиков, которые пытаются использовать разработанный вами класс, функцию или метод.

В этой статье мы рассмотрим распространенные форматы строк документации Python и способы создания автоматизированных строк документации для функций, классов и методов Python с использованием autoDocstring и VSCode.

Распространенные форматы строк документации Python

Это некоторые часто используемые форматы строк документации Python[1]. Как правило, форматы строк документации включают следующие элементы:

  • Описание того, что делает функция
  • Аргументы: описания и типы данных
  • Возвращаемые значения: описания и типы данных
  • Описание возникающих ошибок

Google

def abc(a: int, c = [1,2]):
    """_summary_
    Args:
        a (int): _description_
        c (list, optional): _description_. Defaults to [1,2].
    Raises:
        AssertionError: _description_
    Returns:
        _type_: _description_
    """
    if a > 10:
        raise AssertionError("a is more than 10")
    return c

NumPy

def abc(a: int, c = [1,2]):
    """_summary_
    Parameters
    ----------
    a : int
        _description_
    c : list, optional
        _description_, by default [1,2]
    Returns
    -------
    _type_
        _description_
    Raises
    ------
    AssertionError
        _description_
    """
    if a > 10:
        raise AssertionError("a is more than 10")
    return c

Сфинкс

def abc(a: int, c = [1,2]):
    """_summary_
    :param a: _description_
    :type a: int
    :param c: _description_, defaults to [1,2]
    :type c: list, optional
    :raises AssertionError: _description_
    :return: _description_
    :rtype: _type_
    """
    if a > 10:
        raise AssertionError("a is more than 10")
    return c

PEP257

def abc(a: int, c = [1,2]):
    """_summary_
    Arguments:
        a -- _description_
    Keyword Arguments:
        c -- _description_ (default: {[1,2]})
    Raises:
        AssertionError: _description_
    Returns:
        _description_
    """
    if a > 10:
        raise AssertionError("a is more than 10")
    return c

Создание автоматической строки документации в VsCode

В этом разделе мы рассмотрим примеры того, как автоматически генерировать строку документации в VSCode.

Настраивать

Для создания автоматической строки документации в VSCode нам потребуется

  1. VSCode
  2. Установлено расширение VSCode autoDocstring
  3. Python 3.5 и выше

Настройки VSCode

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

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

Строка документации для функции

Давайте напишем простую функцию для сложения двух целочисленных значений.

def add_two_values(x, y):
    return x + y

Чтобы сгенерировать строку документации, поместите курсор в строку непосредственно под определением функции (т. е. под ключевым словом def) и выполните любой из следующих шагов:

  1. Начните строку документации с тройных двойных или тройных одинарных кавычек и нажмите клавишу Enter
  2. Используйте сочетание клавиш CTRL+SHIFT+2 для Windows или CMD+SHIFT+2 для Mac.
  3. Используйте Generate Docstring из палитры команд VsCode

Это заполнит тело функции следующим образом.

def add_two_values(x, y):
    """_summary_
    Args:
        x (_type_): _description_
        y (_type_): _description_
    Returns:
        _type_: _description_
    """
    return x + y

_summary_, _type_ и _description_ — это заполнители, которые нам нужно заменить реальными описаниями.

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

def add_two_values(x:int, y:int)->int:
    return x + y

После создания строки документации тело функции будет заполнено следующим образом.

def add_two_values(x:int, y:int)->int:
    """_summary_
    Args:
        x (int): _description_
        y (int): _description_
    Returns:
        int: _description_
    """
    return x + y

Обратите внимание, что заполнители _type_ теперь заполнены типом данных аргумента и возвращаемого значения.

Большинство форматов строк документации также включают описание возникшей ошибки. Давайте поднимем TypeError, если аргументы x или y не являются целыми числами.

def add_two_values(x:int, y:int)->int:
    if not all([isinstance(i, int) for i in [x,y]]):
        raise TypeError('inputs must be integer')
    else:
        return x + y

Вновь сгенерированная строка документации будет включать подраздел, описывающий возникшие ошибки. Вот что мы получим после замены _description_ и _summary_placeholders.

def add_two_values(x:int, y:int)->int:
    """Add two values and return their sum.
    Args:
        x (int): first value
        y (int): second value
    Raises:
        TypeError: input values must be integers
    Returns:
        int: sum of input values
    """
    if not all([isinstance(i, int) for i in [x,y]]):
        raise TypeError('inputs must be integer')
    else:
        return x + y

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

Аналогичный метод может быть расширен для строк документации класса и метода класса.

Заключение

В этой статье мы рассмотрели следующее:

  1. Важность строк документации
  2. Общие форматы строк документации
  3. Автоматическое создание строк документации в VsCode с помощью AutoDocString

Строки документации являются важным компонентом любого кода, поскольку они помогают разработчикам понять общую функциональность функции, класса и модуля. Представьте себе путаницу, если библиотеки для обработки данных, такие как scikit-learn, pandas и NumPy, не поставляются со строками документации! Удачного документирования!

Присоединяйтесь к Medium, чтобы читать больше подобных статей!



Присоединяйтесь к Medium по моей реферальной ссылке — Эдвин Тан
Прочитайте все статьи Эдвина Тана (и тысяч других авторов на Medium). Ваш членский взнос напрямую поддерживает Edwin…medium.com



Ссылка

[1] https://github.com/NilsJPWerner/autoDocstring/tree/master/docs