python - 在类方法文档字符串中使用字符串格式

Question

我有一个包含几个类似方法的类，每个方法都有很长的文档字符串，这些方法相似但在几个短语/单词方面有所不同。我想构建一个文档字符串模板，然后对其应用字符串格式。下面是一个笨拙的实现，其中 __doc__s 定义在类方法之后。

capture_doc = """
%(direc)s normal.

a %(sym)s b."""

class Cls():    
    def a(self):
        pass
    def b(self):
        pass
    a.__doc__ = capture_doc % {'direc' : 'below', 'sym' : '<'}     
    b.__doc__ = capture_doc % {'direc' : 'above', 'sym' : '>'}

c = Cls()    
print(c.a.__doc__)

below normal.

a < b.

问题:是否有 Python 文档或 PEP 规定的方法来执行此操作？我想让事情保持基本，我见过 @Appender decorator 的使用但认为这对我的需求来说有点花哨。

Answer 1

你不应该这样做。您似乎认为您的文档字符串应该只为那些使用您的代码并需要帮助了解它的工作原理的人提供服务。

Docstrings 应该为那些阅读您的代码的相关对象提供某种形式的文档，因此这使您的 docstrings 值(value)减半。我怀疑任何人都愿意经历不得不格式化这些字符串(在他们的头脑中或使用解释器)来弄清楚你的代码做什么或它是如何工作的麻烦。

来自 PEP 257 :

What is a Docstring?

A docstring is a string literal that occurs as the first statement in a module, function, class, or method definition. Such a docstring becomes the __doc__ special attribute of that object.

[强调我的]

对于您的实现，有人可能会迂腐地争辩说您没有文档字符串，尽管有 __doc__ 属性。