我正在编写一个轻量级类,其属性旨在公开访问,并且仅有时在特定实例中被覆盖。就此而言,Python 语言中没有为类属性或任何类型的属性创建文档字符串的规定。记录这些属性的预期和支持方式是什么?目前我正在做这样的事情:
class Albatross(object):
"""A bird with a flight speed exceeding that of an unladen swallow.
Attributes:
"""
flight_speed = 691
__doc__ += """
flight_speed (691)
The maximum speed that such a bird can attain.
"""
nesting_grounds = "Raymond Luxury-Yacht"
__doc__ += """
nesting_grounds ("Raymond Luxury-Yacht")
The locale where these birds congregate to reproduce.
"""
def __init__(self, **keyargs):
"""Initialize the Albatross from the keyword arguments."""
self.__dict__.update(keyargs)
这将导致类的文档字符串包含初始标准文档字符串部分,以及通过对__doc__
.
尽管在docstring style Guidelines中似乎没有明确禁止这种风格,但也没有提到它作为一个选项。这里的优点是它提供了一种在属性定义旁边记录属性的方法,同时仍然创建一个可呈现的类文档字符串,并且避免编写重复来自文档字符串的信息的注释。我仍然有点恼火,我实际上必须写两次属性;我正在考虑使用文档字符串中值的字符串表示形式至少避免默认值的重复。
这是对特设社区公约的严重违反吗?没事吧?有没有更好的办法?例如,可以创建一个包含属性值和文档字符串的字典,然后将内容添加到类__dict__
中,并在类声明的末尾添加文档字符串;这将减少两次键入属性名称和值的需要。 编辑:我认为最后一个想法实际上是不可能的,至少在没有从数据动态构建整个类的情况下是不可能的,除非有其他原因,否则这似乎是一个非常糟糕的主意。
我对 python 还很陌生,仍在研究编码风格的细节,所以也欢迎不相关的批评。