Docstring 风格：我真的应该拥有这么长的时间吗？

Question

我有一个风格问题：这是专门针对 Python 的，但我也经常在其他语言中对此感到疑惑。

我有一个要到处返回的对象：它是一个包含许多键的字典。我的模块的主要目的是一个函数返回这个字典；该模块的其余部分只是此功能的实现。在该主要功能的文档字符串中，我已经帮助记录了键的确切含义：

"""
Returns:
    None if the ROP should not be replaced, or a list of dictionaries
    corresponding to commands that should be run sequentially. Each
    dictionary contains the following keys:
        'command': a command that should be run in a shell
        'service': a string for the service that should be used, or None if any service can be used
        'cleanup_sequences': a list of hash-padded file sequences that should be cleaned up
        'cleanup_files': a list of files that should be cleaned up
        'log_sequences': a list of hash-padded file sequences that should be logged
        'log_files': a list of file that should be logged
        'start_frame': the first simulation frame / the first frame to be cleaned up
        'end_end': the last simulation frame / the last frame to be cleaned up
"""

不幸的是，这个对象在被模块中的主函数返回之前要经过三个其他函数。因此，我在每个文档字符串中为这三个其他函数中的每一个都包含了关于每个文档字符串中的键的整个简介。

这本身并不可怕：但它有很多重复的行，而且如果我更改这本字典中的键，这也是一大堆维护。

你们以前遇到过这种情况吗？由于键总是相同的，我想知道是否应该用自己的文档字符串将它包装在我自己的类“MyDictionaryClass”中，然后在函数的文档字符串中我可以说“返回：MyDictionaryClass 的实例”。但是，我不确定我应该使用什么样的对象——在 C++ 中，我可能会 typedef 到某种命名映射。

感谢 Python 大师的任何建议！

Answer 1

不是大师，但我遇到了同样的问题。我确实制作了自己的字典：

class MyDictionary( dict ) :
    def __init__(self, *arg, **kwargs ):
        # do some stuff for instance check mandatory keys are present
        super(self.__class__, self).__init__( *arg, **kwargs )

然后我会记录我的函数返回 MyDictionary 的字符串注释