简介

此 PEP 描述了 Python 2.0 的“属性文档字符串”提案。此 PEP 跟踪此功能的状态和所有权。它包含对该功能的描述，并概述了支持该功能所需的更改。此文件的 CVS 修订历史记录包含权威的历史记录。

基本原理

此 PEP 提出对 Python 当前处理嵌入在 Python 代码中的文档字符串的方式进行少量添加。

Python 目前仅处理直接出现在类定义、函数定义之后或作为模块中第一个字符串字面量出现的文档字符串的情况。字符串字面量添加到相关对象下的 __doc__ 属性中，并且从那时起可用于内省工具，这些工具可以提取包含的信息以用于帮助、调试和文档目的。

出现在上述位置以外的文档字符串将被简单地忽略，并且不会生成任何代码。

以下是一个示例

class C:
    "class C doc-string"

    a = 1
    "attribute C.a doc-string (1)"

    b = 2
    "attribute C.b doc-string (2)"

文档字符串 (1) 和 (2) 当前被 Python 字节码编译器忽略，但显然可以很好地用于记录在其之前的命名赋值。

此 PEP 提出通过为将内容添加到其出现的对象中（在新的生成的属性名称下）提出语义来利用这些情况。

此方法背后的最初想法也启发了上述示例，目的是能够对类属性进行内联文档，这些属性目前只能在类的文档字符串中或使用不可用于内省的注释进行文档记录。

实现

文档字符串由字节码编译器作为表达式处理。当前的实现对上面提到的少数几个位置进行了特殊处理以利用这些表达式，但在其他情况下完全忽略这些字符串。

为了能够使用这些文档字符串记录命名赋值（这例如定义类属性的自然方式），编译器必须跟踪最后分配的名称，然后使用此名称通过将其存储为常量来将文档字符串的内容分配给包含对象的属性，然后在对象构造期间将其添加到对象的命名空间中。

为了保留诸如继承和隐藏 Python 特殊属性（以开头和结尾两个下划线为特征的属性）之类的功能，必须应用特殊的名称混淆，该混淆唯一地识别文档字符串属于名称赋值，并允许通过检查命名空间来稍后找到文档字符串。

以下名称混淆方案实现了以上所有功能

__doc_<attributename>__

为了跟踪最后分配的名称，字节码编译器将此名称存储在编译结构的一个变量中。此变量默认为 NULL。当它看到一个文档字符串时，它会检查该变量并使用该名称作为上述名称混淆的基础，以生成将文档字符串隐式分配给混淆名称。然后它将变量重置为 NULL 以避免重复赋值。

如果该变量不指向名称（即为 NULL），则不会进行任何赋值。这些将像以前一样继续被忽略。所有经典的文档字符串都属于这种情况，因此不会进行重复赋值。

在上面的示例中，这将导致创建以下新的类属性

C.__doc_a__ == "attribute C.a doc-string (1)"
C.__doc_b__ == "attribute C.b doc-string (2)"

在 SourceForge 上的 Python 2.0 当前 CVS 版本的补丁中实现了上述内容，可在 [1] 获取。

实现的注意事项

由于实现不会在处理非表达式（例如函数定义）时重置编译结构变量，因此最后分配的名称将保持有效，直到下一个赋值或下一个文档字符串出现。

这可能导致文档字符串和赋值可能由其他表达式分隔的情况

class C:
    "C doc string"

    b = 2

    def x(self):
        "C.x doc string"
         y = 3
         return 1

    "b's doc string"

由于方法“x”的定义当前不会重置使用的赋值名称变量，因此当编译器到达文档字符串“b’s doc string”时它仍然有效，因此将字符串分配给 __doc_b__。

解决此问题的一种可能方法是在编译器中为所有非表达式节点重置名称变量。

可能的问题

尽管可能性极低，但属性文档字符串可能会意外地连接到属性的值

class C:
    x = "text" \
        "x's docstring"

尾随斜杠将导致 Python 编译器连接属性值和文档字符串。

但是，现代语法突出显示编辑器会轻松地使此意外可见，并且只需在属性定义和文档字符串之间插入空行，您就可以完全避免可能的连接，因此问题可以忽略不计。

另一个可能的问题是使用三引号字符串作为注释代码部分的方法。

如果碰巧在注释字符串的开头之前有一个赋值，则编译器会将注释视为文档字符串属性并对其应用上述逻辑。

除了为其他未记录的属性生成文档字符串之外，没有其他中断。

来自我们 BDFL 的评论

Guido 对 PEP 的早期评论

我“有点”喜欢拥有属性文档字符串的想法（这意味着它对我来说并不重要），但我对您当前的提议有两个不满意的地方

1. 您提出的语法过于模棱两可：正如您所说，独立的字符串字面量用于其他目的，并且可能会突然变成属性文档字符串。
2. 我也不喜欢访问方法（__doc_<attrname>__）。

作者的回复

> 1. The syntax you propose is too ambiguous: as you say, stand-alone
>    string literal are used for other purposes and could suddenly
>    become attribute docstrings.

这可以通过在编译器中引入一些额外的检查来修复，以重置编译器结构中的“文档属性”标志。

> 2. I don't like the access method either (``__doc_<attrname>__``).

任何其他名称都可以。它只需要满足以下条件

• 必须以两个下划线开头（以匹配 __doc__）
• 必须可以使用某种形式的检查进行提取（例如，通过使用包含某些固定名称部分的命名约定）
• 必须与类继承兼容（即应存储为属性）

后来在 2001 年 3 月，Guido 在 python-dev 上宣布了此 PEP。（在发送给此 PEP 作者的私人邮件中提到了他拒绝的原因）

…

它可能有用，但我真的讨厌提议的语法。

a = 1
"foo bar"
b = 1

我真不知道“foo bar”是 a 还是 b 的文档字符串。

…

您可以使用此约定

a = 1
__doc_a__ = "doc string for a"

这使其在运行时可用。

> Are you completely opposed to adding attribute documentation
> to Python or is it just the way the implementation works ? I
> find the syntax proposed in the PEP very intuitive and many
> other users on c.l.p and in private emails have supported it
> at the time I wrote the PEP.

这不是实现，而是语法。它没有传达变量和文档字符串之间足够清晰的耦合。

版权

本文档已置于公共领域。

参考文献