如何使用Python数据类记录类的构造函数？

Question

我有一些现有的Python 3.6代码，我想转移到Python 3.7数据类。我有__init__方法和漂亮的docstring文档，指定构造函数采用的属性及其类型。

但是，如果我在3.7中更改这些类以使用新的Python数据类，则构造函数是隐式的。在这种情况下，如何提供构造函数文档？我喜欢数据类的想法，但如果我不得不放弃使用它们的清晰文档。

编辑澄清我目前正在使用docstrings

Answer 1

在the sphinx docs中描述的拿破仑风格的文档字符串（参见ExampleError类对它的看法）明确触及你的情况：

__init__方法可以记录在类级文档字符串中，也可以记录在__init__方法本身的文档字符串中。

如果你不想要这种行为，你必须explicitly tell sphinx，构造函数docstring和类docstring是不一样的。

这意味着，您只需将构造函数信息粘贴到类docstring的主体中即可。

---

如果您从文档字符串构建文档，这些是可以实现的粒度：

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 docs看到这个例子：

@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装饰器后面的内联注释中添加解释或链接到文档。如果您确实需要数据类的docstring，我建议将构造函数docstring放在类docstring中。对于上面的例子：

'''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
'''