在类方法文档字符串中使用字符串格式
问题描述:
我有一个类有几个类似的方法,每个类都有很长的文档字符串类似,但对于几个短语/单词有所不同。我想构建一个文档字符串模板,然后将字符串格式应用到它。下面是一个笨拙的实现,其中__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
decorator,但认为这对我的需求有点花哨。
答
你不应该这样做。你似乎认为你的文档字符串应该只为那些使用你的代码的人提供服务,并且需要帮助以及它的工作原理。
Docstrings应该为您的代码提供某种形式的关联对象的文档,用于那些阅读,因此这使得您的文档字符串成为其一半的价值。我怀疑任何人都会喜欢经历这样的麻烦:必须格式化这些字符串(在他们的脑海中或者使用解释器)来弄清楚你的代码是干什么的,或者说它是如何工作的。
从PEP 257:
什么是文档字符串?
文档字符串是一个字符串文字发生如在模块,函数,类,或方法定义的第一个语句 。这样的对象的特殊属性成为该特定属性的对象的文档字符串 。
[重点煤矿]
您的实现,人们可以争辩迂腐你没有文档字符串尽管__doc__
属性。
谢谢,好吧。因此,关于我的问题中的链接“熊猫”代码,你会说实现也是不被接受的吗?另外,正如我提到的问题,这是你的意见还是蟒蛇神已经正式颁布的东西? –
@BradSolomon这取决于熊猫核心开发者。更重要的是,对于那些文档来说,似乎要长得多,以便不需要稍作修改就可以重复。在这里,你有几个角色,我不认为重复文件嘲弄干。 –