Invalid help message inside interactive help utility

[ronaldpetty]

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.
>>> 

Linked PRs

• gh-94466: Improve 'help' message in interactive pydoc #148863

[matthew-fogel]

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 suppose I would have expected something like, "cannot use help() inside of help(), use help instead".

I agree that the ImportError raised in the method here could be read misleadingly:

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

As I understand it from the docs linked above, the function call help(print) should be run from an
interactive Python prompt to get help information on print. While in the interactive Python prompt, if the user starts an interactive help session using help(), then print should be called to get help information on print. The last line in the above error message is incorrect. If the user is in the interactive help utility, they should use str for the help on the str class, not help(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:

(base) C:>pydoc notarealfunction
No Python documentation found for 'notarealfunction'.
Use help() to get the interactive help utility.
Use help(str) for help on the str class.

As you can see below, following these instructions does not work outside of the Python interactive prompt:

(base) C:>help(print)
This command is not supported by the help utility. Try "(print) /?".

(base) C:>help()
This command is not supported by the help utility. Try "() /?".

As a solution I lean towards is removing these two lines from the ImportError since they are not correct in all situations.

Use help() to get the interactive help utility.
Use help(str) for help on the str class.

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]

See also #104471 for a somewhat related issue.

[matthew-fogel]

See also #104471 for a somewhat related issue.

Thanks!