python / python/cpython

"See help(type(self)) for accurate signature" in `__init__`'s docstring is misleading

未關閉
#121,394 2 則留言 0 個 reaction 已指派 0 人 在 GitHub 檢視

還沒有人認領這個 Issue。

interpreter-core type-feature
主要語言
Python
星號
77.2k
分支
35.9k
PR 合併指標
PR 指標待擷取

描述

Feature or enhancement

Let's say I have a simple class:

class A:
    def __init__(self, a):
        self.a = a

help(A) will produce:

Help on class A in module __main__:

class A(builtins.object)
 |  A(a)
 |
 |  Methods defined here:
 |
 |  __init__(self, a)
 |      Initialize self.  See help(type(self)) for accurate signature.
 |
 |  ----------------------------------------------------------------------
 |  Data descriptors defined here:
 |
 |  __dict__
 |      dictionary for instance variables
 |
 |  __weakref__
 |      list of weak references to the object

Note that the signature is already accurate. But, now I see this message: See help(type(self)) for accurate signature.. Let's try to do something about it.

Let's follow the instruction:

class A:
    def __init__(self, a):
        help(type(self))
        self.a = a

It will produce:

Help on class A in module __main__:

class A(builtins.object)
 |  A(a)
 |
 |  Methods defined here:
 |
 |  __init__(self, a)
 |      Initialize self.  See help(type(self)) for accurate signature.
 |
 |  ----------------------------------------------------------------------
 |  Data descriptors defined here:
 |
 |  __dict__
 |      dictionary for instance variables
 |
 |  __weakref__
 |      list of weak references to the object

Exactly the same signature. With exactly the same message.

Now, let's try a different example, an empty class:

class B: ...

help(B.__init__) will say:

Help on wrapper_descriptor:

__init__(self, /, *args, **kwargs) unbound builtins.object method
    Initialize self.  See help(type(self)) for accurate signature.

And help(B) will say (notice that there would be no __init__ at all):

Help on class B in module __main__:

class B(builtins.object)
 |  Data descriptors defined here:
 |
 |  __dict__
 |      dictionary for instance variables
 |
 |  __weakref__
 |      list of weak references to the object

Is this message See help(type(self)) for accurate signature really useful? When do users benefit from seeing it?

貢獻指南

開啟貢獻指南

從這裡開始

  1. 先讀完整個 Issue,再讀專案的貢獻指南。
  2. 在 Issue 下留言說明你要接手 —— 這能避免兩個人做同樣的事。
  3. Fork 儲存庫,在一個分支上完成修改。
  4. 送出 Pull Request,並在描述裡引用這個 Issue 編號。

研究方向

使用 help(A)、help(A.init) 和一個空類別 B 重現回報的輸出。追蹤內建 init 的文件字串和 pydoc 類別輸出的產生位置,然後找出相關的回歸測試區域。完成的條件是:誤導性的指引得到一致的修正或移除,且 help 輸出有測試涵蓋。

由索引模型根據 Issue 內容生成。

評估

技術堆疊
python
領域
documentation
Issue 類型
功能
難度
3/5
預估耗時
1-2 天
活躍度
停滯
描述清晰度
基本清楚
新手友好度
35/100

把新 issue 寄到你的電子郵件信箱

精選適合新手參與的 GitHub issue 摘要。