Make help() beginner helpful when no PAGER or LESS variable

[nedbat]

BPO	21625
Nosy	@terryjreedy, @jcea, @nedbat, @stevendaprano, @bitdancer, @serhiy-storchaka, @eryksun, @ZackerySpytz, @nagarajan
PRs	gh-65824: Improve help() when MANPAGER and PAGER variables are not set #21520

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2014-06-01.12:04:38.377>
labels = ['type-feature', '3.8']
title = 'Make help() beginner helpful when no PAGER or LESS variable'
updated_at = <Date 2020-07-18.16:49:12.756>
user = 'https://github.com/nedbat'

bugs.python.org fields:

activity = <Date 2020-07-18.16:49:12.756>
actor = 'nagarajan'
assignee = 'none'
closed = False
closed_date = None
closer = None
components = []
creation = <Date 2014-06-01.12:04:38.377>
creator = 'nedbat'
dependencies = []
files = []
hgrepos = []
issue_num = 21625
keywords = ['patch']
message_count = 9.0
messages = ['219497', '219516', '219520', '219547', '219566', '219595', '219596', '338493', '373909']
nosy_count = 9.0
nosy_names = ['terry.reedy', 'jcea', 'nedbat', 'steven.daprano', 'r.david.murray', 'serhiy.storchaka', 'eryksun', 'ZackerySpytz', 'nagarajan']
pr_nums = ['21520']
priority = 'normal'
resolution = None
stage = 'patch review'
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue21625'
versions = ['Python 3.8']

Linked PRs

• gh-65824: Improve the "less" prompt in pydoc #116050
• gh-65824: Add "Help on ..." to the "less" prompt in pydoc #116183

[nedbat]

From the #python IRC channel:

[07:55:29] tonysar	 hello.new to programming and python, i use mac terminal but problem i have is , when i use help function of python to look up something , i lose my prompt and i have no idea how to go back , what i do is close the terminal and restart , is there any way to go back to prompt again ?
[07:57:12] nedbat	 tonysar: type a "q"
[07:57:26] nedbat	 tonysar: it works like the unix-standard "more" program.
[07:58:10] nedbat	 tonysar: looking at it through your eyes, it's crazy-unhelpful that it only accepts a q....
[07:58:42] tonysar	 nedbat: thanks but i can not type anything , after using help(object) i get the info on object i look and there is END at the bottom of python terminal and i can not type anything after or before
[07:59:03] nedbat	 tonysar: what happens if you type q ?
[07:59:24] nedbat	 tonysar: just the single letter q
[07:59:41] tonysar	 nedbat . thanks
[07:59:47] tonysar	 the q worked
[08:01:08] tonysar	 nedbat:Thanks. typing q got me back to prompt again . thanks again

Why does help() enter a more-mode for even short help? Why doesn't ENTER get you out of it? Why doesn't the prompt have a suggestion of how to get out of it? Why does it clear the screen when you are done with it, removing all the help from the screen?

It seems very geeky, and not that help-ful. I'm sure there's something we can do to make this a little easier for newbs.

[eryksun]

Why does help() enter a more-mode for even short help?

more exits if there's less than a page of a text. The default for less is to quit when "q" is entered. You may be interested in the option -e (quit-at-eof).

Why doesn't ENTER get you out of it?

ENTER scrolls. Type a number N to scroll by N lines.

Why does it clear the screen when you are done with it,
removing all the help from the screen?

The option -X (no-init) should stop less from clearing the screen.

Why doesn't the prompt have a suggestion of how to get out of it?

I guess no one thought to add that when less is used.

You can customize the pager using the PAGER environment variable, as used by other commands such as man.

    $ PAGER='less -eX' python3 -c 'help(help)'
    Help on _Helper in module site object:
    
    class _Helper(builtins.object)
    [...]

You can also set pydoc.pager directly, which is what IDLE does:

    >>> pydoc.pager = pydoc.plainpager
    >>> help(help)
    Help on _Helper in module site object:
    [...]

plainpager is the default if the TERM environment variable is dumb or emacs, or if sys.stdout isn't a tty. Otheriwse if the system has neither less nor more, the pager is set to pydoc.ttypager.

On Windows, text is written to a temp file using tempfilepager. Other platforms pipe the text using pipepager. This should also work for Windows in Python 3, which implements os.popen with subprocess.Popen. Here's a test using GnuWin32 head.exe and tr.exe:

    >>> cmd = 'head -n3 | tr [:lower:] [:upper:]'    
    >>> pydoc.pager = lambda t: pydoc.pipepager(t, cmd)
    >>> help(help)
    HELP ON _HELPER IN MODULE _SITEBUILTINS OBJECT:
    
    CLASS _HELPER(BUILTINS.OBJECT)

[nedbat]

Thanks, this is a very complete explanation of the machinery behind the scenes. I think we would do beginners a service if we made the behavior a bit less obscure. Are there ways that we could (for example) have the prompt say "END (q to quit)" instead of just "END"?

[serhiy-storchaka]

Are there ways that we could (for example) have the prompt say "END (q to quit)" instead of just "END"?

Add following command to your profile file (~/.profile, ~/bashrc, or ~/.bash_aliases):

export LESS='-PEND (q to quit)'

And please don't break help(). It works as expected (to Unix users) and is enough configurable.

[nedbat]

Serhiy, thanks for the configuration tip. But you seem to be missing my point, which is that beginners need the default to be a little more friendly. I don't want to make it bad for experienced users, of course. I doubt Unix users will be confused by seeing "END (q to quit)" as a prompt.

[eryksun]

You can use '-P?e(END) .(q to quit)' to add (END) just on the last line. Or show the line count instead:

os.environ['LESS'] = '-Pline %lB?L/%L. (press h for help or q to quit)'

[bitdancer]

There is also an option to make less quit if enter is pressed on the last line (-e/--quit-at-eof).

These more beginner friendly options could be provided by pydoc if there is no existing PAGER or LESS environment variable.

[terryjreedy]

I recently opened Python in a Mac Terminal (bash) window, tried help(ob), and being a beginner in this situation, had the same terrible frustrating experience. I am leaving this open to implement David Murray's suggestion and changed the title accordingly.

On Windows, in Command Prompt and Power Shell, a prompt appears when help output is done and the text remains. This is the same as when one enters any other Python statement that produces output. (The only difference is the intermediate paging.) I think that this standard Python behavior, or something close, should be the default help behavior on all systems. (It is on IDLE.)

[nagarajan]

I would request us to think about a couple more options while this is under consideration...

Do we want to also add the flags -X and -F to the less options?

The -X flag gets less to show its output inline, instead of a separate screen. The advantage here is that users can now see the last viewed help page right above the prompt even after quitting help. It helps immensely to be able to see the help and write statements based on the help. The minor downside is that the last statements typed on the python prompt have now scrolled farther up.

The -F (or --quit-if-one-screen) flag exits helps automatically if the help contents fit less than one screen-full. This is only useful when used in conjunction with the -X flag. If we do decide to use the -X flag, then this flag becomes an obvious choice.

If we do choose to use these flags, the less command now becomes

less "-P?e(END) .(q to exit help) " -X --quit-if-one-screen --quit-at-eof

[serhiy-storchaka]

#116050 is an alternative solution, heavily inspired by the GNU implementation of man. The differences from #21520:

• It works also when MANPAGER or PAGER environment variables are set to less.
• It works also if they are set to a wrapper around less.
• It allows to override default settings by specifying less with options in MANPAGER or PAGER.
• It outputs also the line number (help for navigation commands) and the percentage).
• It outputs also "press h for help" to help to learn less.

[serhiy-storchaka]

#116183 adds "Help on XXX" to the less prompt (man adds "Manual page XXX"). It is more invasive change, and it was not discussed above, so it has been separated in a separate PR.

Now the prompt looks like:

 Help on decimal line 467 (press h for help or q to quit)

or

 Help on decimal line 467/1978 24% (press h for help or q to quit)

[hugovk]

Triage: the linked PRs are merged, can this be closed?

[serhiy-storchaka]

I only made changes that I thought were worth making. But there were other proposals. I do not know whether this is enough for the OP.