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

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规定的方式来做到这一点？我想保持基本的东西，我已经看到使用@Appenderdecorator，但认为这对我的需求有点花哨。

Answer 1

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

Docstrings应该为您的代码提供某种形式的关联对象的文档，用于那些阅读，因此这使得您的文档字符串成为其一半的价值。我怀疑任何人都会喜欢经历这样的麻烦：必须格式化这些字符串（在他们的脑海中或者使用解释器）来弄清楚你的代码是干什么的，或者说它是如何工作的。

从PEP 257：

什么是文档字符串？

文档字符串是一个字符串文字发生如在模块，函数，类，或方法定义的第一个语句 。这样的对象的特殊属性成为该特定属性的对象的文档字符串 。

[重点煤矿]

您的实现，人们可以争辩迂腐你没有文档字符串尽管__doc__属性。