Как мне документировать конструктор для класса, используя классы данных Python?

Question

У меня есть существующий код Python 3.6, который я хотел бы переместить в классы данных Python 3.7. У меня есть __init__ методы с хорошей документацией документации, определяющие атрибуты, которые принимают конструкторы, и их типы.

Однако, если я изменю эти классы, чтобы использовать новые классы данных Python в 3.7, конструктор будет неявным. Как мне предоставить конструкторскую документацию в этом случае? Мне нравится идея классов данных, но нет, если я вынужден отказаться от четкой документации, чтобы использовать их.

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

Answer 1

Строки документов наполеоновского типа, как они описаны в документах sphinx (см. Класс ExampleError, чтобы узнать о них), явно касаются вашего случая:

Метод __init__ может быть задокументирован либо в строке документации уровня класса, либо в виде строки документации самого метода __init__.

И если вам не нужно это поведение, вы должны явно сказать sphinx , что строка документации конструктора и строка документации класса - это не одно и то же.

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

---

В случае, если вы строите документы из своих строк документации, можно достичь следующих гранулярностей:

1) Минимальный минимум:

@dataclass
class TestClass:
    """This is a test class for dataclasses.

    This is the body of the docstring description.
    """
    var_int: int
    var_str: str

2) Описание дополнительных параметров конструктора:

@dataclass
class TestClass:
    """This is a test class for dataclasses.

    This is the body of the docstring description.

    Args:
        var_int (int): An integer.
        var_str (str): A string.

    """
    var_int: int
    var_str: str

3) Описание дополнительного атрибута:

@dataclass
class TestClass:
    """This is a test class for dataclasses.

    This is the body of the docstring description.

    Attributes:
        var_int (int): An integer.
        var_str (str): A string.

    """
    var_int: int
    var_str: str

---

Описания параметров и атрибутов, конечно, тоже можно комбинировать, но, поскольку классы данных должны быть прямыми отображениями, я не вижу причин для этого.

На мой взгляд, 1) подходит для небольших или простых классов данных - он уже включает сигнатуру конструктора с соответствующими им типами, что достаточно для класса данных. Если вы хотите сказать больше о каждом атрибуте, лучше всего подойдет 3) .

Answer 2

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

@dataclass
class InventoryItem:
    '''Class for keeping track of an item in inventory.'''
    name: str
    unit_price: float
    quantity_on_hand: int = 0

    def total_cost(self) -> float:
        return self.unit_price * self.quantity_on_hand

Если вы не ожидаете, что читатели вашего кода будут знать, как работают классы данных, вы можете пересмотреть их использование или добавление объяснения или ссылки на документы во встроенном комментарии после декоратора @dataclass. Если вам действительно нужна строка документации для класса данных, я бы порекомендовал поместить строку документации конструктора в строку класса. Для примера выше:

'''Class for keeping track of an item in inventory.

Constructor arguments:
:param name: name of the item
:param unit_price: price in USD per unit of the item
:param quantity_on_hand: number of units currently available
'''