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

Question

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

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 装饰器，但我认为那对我的需求有点花哨。

- Brad Solomon

Answer 1

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

文档字符串应该为那些阅读你的代码的人提供与相关对象有关的某种形式的文档，因此这使得你的文档字符串只有一半的价值。我怀疑任何人都不愿意费力地格式化那些字符（在他们的头脑中或使用解释器），以弄清楚你的代码是做什么或如何工作的。

来自PEP 257：

什么是文档字符串？

文档字符串是出现在模块、函数、类或方法定义中的一个字符串字面量，这样的文档字符串成为该对象的__doc__特殊属性。

[重点强调]

使用你的实现，有人可能会严格地争论你没有文档字符串，尽管有__doc__属性。

- Moses Koledoye

---

谢谢，说得好。关于我问题中链接的 pandas 代码，您认为这种实现方式也不被看好吗？另外，正如我在问题中所暗示的，这是您的个人意见还是 Python 神明们已经正式颁布的规定？ - Brad Solomon

@BradSolomon 这取决于pandas核心开发人员。此外，这些文档似乎要长得多，以至于重复进行微小修改是不可接受的。在这里，您只有几个字符，我认为重复文档并不违反DRY原则。 - Moses Koledoye

我认为最有力的论据是，将问题中的每个文档都详细说明并不违反“不要重复自己”的原则：这些文档简单明了，长度短小，因此在更新代码时很少会出现什么问题。 - Eric O. Lebigot

我认为大多数文档字符串都是由用户阅读的，而不是阅读源代码的人。库主要是供用户使用的，而不是被外部用户分析、解构或维护的。 - Eric O. Lebigot

最后，我想补充一下技术说明：docstring确实是PEP 257中描述的文字，但问题显然是关于方法文档的，而__doc__是方法的文档（正如https://docs.python.org/3/reference/datamodel.html?highlight=__doc__中反复写到的那样），这也是问题的主题。 - Eric O. Lebigot

“你不应该这样做”不是问题的答案。对于此类情况，例如click使用文档字符串作为帮助文本，存在合法的用例。 - alexia