[docs] [issue12902] help("modules") executes module code

[Terry J. Reedy]

Terry J. Reedy <tjreedy at udel.edu> added the comment:

The immediate issue is improvement of the entries for help and help():

In builtin functions section:

Expand "Invoke the built-in help system." to
"Invoke the built-in help system, which uses *pydoc*."
where *pydoc* is linked to the pydoc section.

Add to the end of the entry something like "As needed, pydoc imports modules to get their doc strings."

The special string 'modules' is not documented in the manual entry for help() itself. That is fine. It does appear in the longer text that appears for 'help()'. That text, where ever it is, could and should have a warning.

"Warning: gathering the results for the topic 'modules' can take considerable time and have side effects as it imports *every* module available to get at its doc string."

A separate issue would be a feature request to not do that (assuming it really does). Given that 'modules' just produces a list of (incomplete) module names, I do not see the point of importing until one requests help on a particular name.

There seems to be a bug. In a fresh 3.2.2 IDLE window, help('modules') produces about 300 names. If I repeat, I get a reduced list of 58 names. These seem to just be the builtin C-coded modules, like 'math', with all Python-coded modules, like 'random', omitted.

----------
assignee:  -> docs at python
components: +Documentation
nosy: +docs at python, terry.reedy
stage:  -> needs patch
versions: +Python 2.7, Python 3.2, Python 3.3

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue12902>
_______________________________________