Repository navigation
Invalid help message inside interactive help utility #94466
Description
Documentation
From REPL, >>> help(help) produces valid output.
From inside interactive help utility, help> help(help), produces less useful output.
I suppose I would have expected something like, "cannot use help() inside of help(), use help instead".
Here is an example.
~$ python3
Python 3.10.4 (main, Apr 2 2022, 09:04:19) [GCC 11.2.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> help(help)
>>> help() # works as expected
Welcome to Python 3.10's help utility!
If this is your first time using Python, you should definitely check out
the tutorial on the internet at https://docs.python.org/3.10/tutorial/.
Enter the name of any module, keyword, or topic to get help on writing
Python programs and using Python modules. To quit this help utility and
return to the interpreter, just type "quit".
To get a list of available modules, keywords, symbols, or topics, type
"modules", "keywords", "symbols", or "topics". Each module also comes
with a one-line summary of what it does; to list the modules whose name
or summary contain a given string such as "spam", type "modules spam".
help> help(help)
No Python documentation found for 'help(help)'.
Use help() to get the interactive help utility.
Use help(str) for help on the str class.
# typing just help works as expected
help>
You are now leaving help and returning to the Python interpreter.
If you want to ask for help on a particular object directly from the
interpreter, you can type "help(object)". Executing "help('string')"
has the same effect as typing a particular string at the help> prompt.
>>>
Activity
matthew-fogel commentedon May 18, 2023
Good day, I was looking for my first docs issue to contribute to. I have some ideas on how to resolve this.
Before answering, I tried this module out myself in Anaconda prompt and read the pydoc module docstring and the documentation for pydoc and help.
I agree that the ImportError raised in the method here could be read misleadingly:
As I understand it from the docs linked above, the function call
help(print)should be run from aninteractive Python prompt to get help information on
print. While in the interactive Python prompt, if the user starts an interactive help session usinghelp(), thenprintshould be called to get help information onprint. The last line in the above error message is incorrect. If the user is in the interactive help utility, they should usestrfor the help on the str class, nothelp(str).Since the method output here already indicates how to use the interactive help utility, I lean against re-documenting the same thing in two different methods if it can be avoided.
There is a second, unrelated docs issue in the same ImportError message.
If the error is raised when using pydoc rather than the Python interactive prompt, the instructions provided are wrong:
As you can see below, following these instructions does not work outside of the Python interactive prompt:
As a solution I lean towards is removing these two lines from the ImportError since they are not correct in all situations.
An alternative is expanding the error message to briefly mention the different ways to call help across the Python interactive interpreter, the interactive help session, and the shell outside the Python interpreter. Since that would re-document things already nicely documented elsewhere, I'm not sure if this option is preferred.
Please let me know what you think and if you have other alternative suggestions. As I am a new contributor to this project, and this change will probably be visible to many users, I recognize I should wait for feedback before opening a PR.
I won't be available to write code in the next few days but would be open to opening a PR over the next few weeks
Thanks for reading. I look forward to everyone's comments!
hugovk commentedon May 27, 2023
See also #104471 for a somewhat related issue.
matthew-fogel commentedon May 27, 2023
Thanks!