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

Question

我有一些现有的Python 3.6代码,我想转移到Python 3.7数据类.我有一些__init__方法,包含很好的文档字符串文档,指定构造函数所采用的属性及其类型.

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

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

Answer 1

狮身人面像文档中描述的拿破仑风格的文档字符串（请参见ExampleError该类的说明）明确涉及您的情况：

__init__方法可以记录在类级别docstring中，也可以记录在__init__方法本身上。

而且，如果您不希望出现这种情况，则必须明确告诉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
class TestClass:
    """This is a test class for dataclasses.

    This is the body of the docstring description.

    """
    var_int: int  #: An integer.

    #: A string.
    #: (Able to have multiple lines.)
    var_str: str

    var_float: float
    """A float. (Able to have multiple lines.)"""

不知道为什么 @Arne 渲染的结果看起来像这样。就我而言，无论文档字符串如何，数据类中的属性都将始终显示。那是：

1）最低限度：

2）附加构造函数参数说明：

3）附加属性说明：

conf.py可能是因为我在我的（Sphinx v3.4.3，Python 3.7）中设置了一些错误：

extensions = [
    "sphinx.ext.napoleon",
    "sphinx.ext.autodoc",
    "sphinx_autodoc_typehints",
    "sphinx.ext.viewcode",
    "sphinx.ext.autosectionlabel",
]

# Napoleon settings
napoleon_google_docstring = True
napoleon_include_init_with_doc = True

Answer 3

数据类的主要优点是它们是自记录的。假设您的代码读者知道数据类是如何工作的（并且属性已适当命名），则带类型注释的类属性应该是构造函数的出色文档。请参阅官方数据类文档中的以下示例：

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