python / python/cpython

`help` function: misleading output in interactive mode, confusing output for `help(help)`

未關閉
#138,094 0 則留言 0 個 reaction 已指派 0 人 在 GitHub 檢視

還沒有人認領這個 Issue。

docs stdlib
主要語言
Python
星號
77.2k
分支
36k
PR 合併指標
PR 指標待擷取

描述

When using the built-in help function in interactive mode, the current output when no topic is found is potentially misleading, in that the suggestions offered are not usable at the interactive help prompt, e.g.:

help> something
No Python documentation found for 'something'.
Use help() to get the interactive help utility.
Use help(str) for help on the str class.

Typing either of the suggested expressions at the help prompt will, of course, not work, because they're meant for use in Python code. And the suggestion about str seems to be irrelevant in interactive mode, where everything is a string anyway. I think it would be better not to offer these suggestions at all when running in interactive mode.

Additionally, running help(help) shows a large amount of irrelevant information related to the _Helper class from _sitebuiltins.py, with the usage instructions buried inside of it:

Output of help(help)
Help on _Helper in module _sitebuiltins object:

class _Helper(builtins.object)
 |  Define the builtin 'help'.
 |
 |  This is a wrapper around pydoc.help that provides a helpful message
 |  when 'help' is typed at the Python interactive prompt.
 |
 |  Calling help() at the Python prompt starts an interactive help session.
 |  Calling help(thing) prints help for the python object 'thing'.
 |
 |  Methods defined here:
 |
 |  __call__(self, *args, **kwds)
 |      Call self as a function.
 |
 |  __repr__(self)
 |      Return repr(self).
 |
 |  ----------------------------------------------------------------------
 |  Data descriptors defined here:
 |
 |  __dict__
 |      dictionary for instance variables
 |
 |  __weakref__
 |      list of weak references to the object

I think this could be improved by showing usage instructions when invoking help(help) from Python, but preserving the current behavior of repeating the intro text when looking up help via the interactive prompt.

I'll put in a PR shortly that attempts to improve both of these.

Linked PRs
  • gh-138095

貢獻指南

開啟貢獻指南

從這裡開始

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

研究方向

從 _sitebuiltins.py 中參照的 _Helper 實作開始,追蹤互動式說明提示如何處理缺少的主題與 help(help)。完成的判定標準是:互動模式不再顯示無法使用的建議,且 help(help) 提供使用說明而不包含無關的類別詳細資訊。

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

評估

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

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

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