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 字符串。
原文地址：https://www.bilibili.com/read/readlist/rl812939