介紹

此 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