PEP 224 – 属性文档字符串

介绍

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

理由

这个 PEP 对 Python 目前的方式提出了一个小小的补充处理嵌入在 Python 代码中的文档字符串。

Python 目前只处理出现的文档字符串的情况紧跟在类定义、函数定义或 AS 之后模块中的第一个字符串文本。添加字符串文本到属性下的问题对象，并且是从那时起，可用于可以提取包含的帮助、调试和文档信息目的。__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 还建议通过提议来利用这些案例用于将其内容添加到其所在对象的语义显示在新生成的属性名称下。

这种方法背后的最初想法也启发了上面的示例是启用类的内联文档属性，目前只能记录在类的 docstring 或使用不可用的注释内省。

实现

文档字符串由字节码编译器作为表达式处理。目前实施的特例为少数几个地点上面提到来使用这些表达式，但除此之外完全忽略字符串。

若要允许使用这些文档字符串来记录名为赋值（这是定义类的自然方式属性），编译器必须跟踪最后一个分配的名称，然后使用此名称分配 docstring 通过以下方式添加到包含对象的属性将其存储为常量，然后将其添加到对象的对象构造期间的命名空间。

为了保留继承和隐藏等功能 Python 的特殊属性（具有前导和尾随双精度的属性）下划线），必须应用一个特殊的名称 mangling，其中唯一地将文档字符串标识为属于该名称赋值，并允许稍后通过检查查找文档字符串命名空间。

以下名称 mangling 方案实现了上述所有目标：

__doc_<attributename>__

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

如果变量不指向名称（即为 NULL），则 no 进行分配。这些将继续被忽略，例如以前。所有经典文档字符串都属于这种情况，所以没有完成重复的分配。

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

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

Python 2.0 当前 CVS 版本的补丁，它实现了以上内容可在 Sourceforge 上找到，网址为

实施注意事项

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

这可能会导致文档字符串和赋值可能用其他表达式分隔：

class C:
    "C doc string"

    b = 2

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

    "b's doc string"

由于方法“x”的定义当前不会重置使用赋值名变量，编译器在编译器时仍然有效到达 docstring “B 的 doc 字符串”，从而分配字符串自。__doc_b__

此问题的可能解决方案是重置名称变量。

可能的问题

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

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

尾部斜杠将导致 Python 编译器连接属性值和 docstring。

现代语法突出显示编辑器可以很容易地做到这一点但是，通过简单地插入空行，事故是可见的在属性定义和文档字符串之间可以避免可能的完全串联，所以问题是微不足道。

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

如果在开始之前碰巧有一项任务注释字符串，则编译器会将注释视为 docstring 属性，并将上述逻辑应用于它。

除了为其他未记录的文档生成文档字符串属性没有破损。

来自我们BDFL的评论

Guido 对 PEP 的早期评论：

我“有点”喜欢拥有属性文档字符串的想法（意思是这对我来说不是很重要）但我有两件事不喜欢您当前的提案：
你提出的语法太模棱两可了：正如你所说，独立字符串文本用于其他目的，可以突然变成属性文档字符串。
我也不喜欢访问方法（）。__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.
这可以通过在编译器重置编译器中的“doc attribute”标志结构。
> 2. I don't like the access method either (``__doc_<attrname>__``).
任何其他名称都可以。它只需要匹配这些标准：
必须以两个下划线开头（以匹配__doc__)
必须可以使用某种形式的检查（例如，通过使用命名约定，包括一些固定名称部分）
必须与类继承兼容（即应存储为属性）

3 月下旬，Guido 于 2001 年 3 月宣布了这个 PEP（在 python-dev）。以下是他拒绝的原因私信给本 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.
这不是实现，而是语法。事实并非如此在变量和 doc 字符串。

版权

本文档已置于公有领域。

The End