可以计算 Python 文档字符串（f 字符串或 % 表达式）吗？

Question

是否可以计算Python文档字符串？我的文档字符串中有很多重复的内容，所以我想使用 f 字符串或 % 样式格式表达式。

当我在文档字符串的位置使用 f 字符串时

• 导入模块会调用处理
• 但是当我检查这样一个函数的

  __doc__ 

  时它是空的
• 当文档字符串是 f 字符串时，sphinx barfs

我确实知道如何在导入后处理文档字符串，但这不适用于 sphinx 识别的对象“doc”字符串，但它不是对象的真正

__doc__

。

Answer 1

Python 中的文档字符串必须是常规字符串文字。

这非常容易测试 - 以下程序不显示文档字符串：

BAR = "Hello world!"

def foo():
        f"""This is {BAR}"""
        pass

assert foo.__doc__ is None
help(foo)

Python 语法文档说 文档字符串必须是“字符串文字”，并且 f 字符串引用的尾部表示它们“不能用作文档字符串”。

所以不幸的是你必须使用

__doc__

属性。

但是，您应该能够使用装饰器来读取

__doc__

属性并将其替换为您想要的任何内容。

Answer 2

我们遇到了同样的问题，我们最终可能会做的是：

BAR = "Hello world!"

class A():
    __doc__ = f"""This is {BAR}"""
    pass

help(A)

Answer 3

有点烦人，但另一种选择是使用像 jinja2 这样的模板引擎生成 python 文件。您将需要另外为您的文件创建模板以及渲染它的逻辑，但最终您将得到一个“正常”Python 文件，其中包含与 sphinx 等兼容的文字文档字符串。