關於實例的 Python __doc__ 文檔

Question

我想提供有關某些動態創建的對象的文檔（在我的程序中），但仍然回退到使用它們的類文檔。 設置__doc__似乎是一種合適的方式。 但是，我在這方面的 Python 幫助中找不到很多細節，在提供實例文檔方面是否存在任何技術問題？ 例如：

class MyClass:
    """
    A description of the class goes here.
    """

a = MyClass()
a.__doc__ = "A description of the object"

print( MyClass.__doc__ )
print( a.__doc__ )

Answer 1

__doc__被記錄為函數的可寫屬性，但不適用於用戶定義類的實例。 例如， pydoc.help(a)將僅考慮在類型上定義的__doc__ 。

其他協議（包括將來的用例）也可以合理地繞過實例dict中定義的特殊屬性。 請參閱數據模型文檔的“ 特殊方法查找”部分，尤其是：

對於自定義類，只有在對對象的類型（而不是在對象的實例字典中）進行定義的情況下，才能保證對特殊方法的隱式調用可以正常工作。

因此，取決於屬性的使用者，您打算執行的操作可能並不可靠。 避免。

一個安全，簡單的替代方法是針對自己的用例使用自己選擇的其他屬性名稱，最好不使用__dunder__語法約定，該約定通常表示為實現和/或stdlib保留某些特定用途的特殊名稱。

Answer 2

存在一些非常明顯的技術問題； 問題是它們對您的用例是否重要。

這是文檔字符串無法使用的一些主要用法：

• help(a) ：類型help(a)在交互終端，你會得到的文檔字符串MyClass ，不是文檔字符串的a 。
• 自動生成的文檔 ：除非您編寫自己的文檔生成器，否則不會理解您a值所做的任何特殊操作。 許多文檔生成器確實可以通過某種方式為模塊和類常量指定幫助，但是我不知道有什么方法可以識別您的習慣用法。
• IDE幫助 ：許多IDE不僅會自動完成表達式，還會在工具提示中顯示相關的文檔字符串。 他們都是靜態地執行此操作的，並且沒有圍繞您的習慣用法設計一些特殊情況的代碼（考慮到這是一個不尋常的習慣用法，它們不太可能具有），因此幾乎可以肯定會獲取類的文檔字符串，而不是對象。

以下是一些可能會有所幫助的地方：

• 來源可讀性 ：作為一個人讀你的來源，我能分辨出的意圖a.__doc__ = …右側附近建設a 。 再說一遍，我可以從Sphinx對常量的評論中輕松地說出相同的意圖。
• 調試 ： pdb對docstrings並沒有真正做很多事情，但是包裹在它上面的一些GUI調試器確實可以做，而且大多數它們可能會顯示a.__doc__ 。
• 自定義動態使用docstring ：顯然，您編寫的任何使用a.__doc__都將獲取實例docstring（如果需要），因此可以使用它執行任何操作。 但是，請記住，如果要定義自己的“協議”，則應使用自己的名稱，而不是為實現保留的名稱。

---

請注意，對於文檔字符串使用描述符，大多數情況都是如此：

>>> class C:
...     @property
...     def __doc__(self):
...         return('C doc')
>>> c = C()

如果鍵入c.__doc__ ，將得到'C doc' ，但是help(c)會將其視為沒有docstring的對象。

---

值得一提的是，使help工作的一些動態代理庫動態生成，這是新課程的原因之一 ，代理到底層類型Spam有一些新的類型像_SpamProxy ，而不是同GenericProxy用於代理類型為Ham s和Eggs 。 前者允許help(myspam)顯示有關Spam動態生成的信息。 但是我不知道這是多么重要 。 通常，您已經需要動態類來進行特殊的方法查找，例如，免費添加動態文檔字符串。

Answer 3

我認為最好通過您的doc字符串將其保留在類下，因為這也將有助於使用該代碼的任何開發人員。 但是，如果您要執行動態操作而需要此設置，那么我看不出為什么不這樣做。 只需了解它會增加一定程度的間接性，這會使其他人不太清楚。

請記住在適用的情況下向KISS致謝：）

Answer 4

我只是偶然發現了這一點，並注意到至少在 python 3.9.5 中，行為似乎發生了變化。

例如使用上面的例子，當我打電話時：

help(a)

我得到：

Help on MyClass in module __main__:

<__main__.MyClass object>
    A description of the object

另外作為參考，請查看pydoc 實現，它顯示：

def _getowndoc(obj):
    """Get the documentation string for an object if it is not
    inherited from its class."""
    try:
        doc = object.__getattribute__(obj, '__doc__')
        if doc is None:
            return None
        if obj is not type:
            typedoc = type(obj).__doc__
            if isinstance(typedoc, str) and typedoc == doc:
                return None
        return doc
    except AttributeError:
        return None