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

Question

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

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

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

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

来自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__ 个属性。

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

Using string formatting within class method docstrings

python

docstring

string-formatting

python-3.x