在类方法docstrings中使用字符串格式

Question

我有一个类有几个类似的方法,每个方法都有相似的长文档字符串,但在几个短语/单词方面有所不同.我想构建一个docstring模板,然后将字符串格式应用于它.下面是一个笨拙的实现,其中__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 装饰师,但认为这对我的需求有点花哨.

Answer 1

你不应该这样做.您似乎认为您的docstring应该只为那些使用您的代码并需要帮助的人提供服务.

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

从PEP 257:

什么是Docstring？

docstring是一个字符串文字,作为模块,函数,类或方法定义中的第一个语句出现.这样的文档字符串 成为该 __doc__对象的特殊属性.

[ 强调我的 ]

随着你的实现,人们可以迂腐地争辩你没有docstrings尽管__doc__属性.