classification
Title: Make help() beginner helpful when no PAGER or LESS variable
Type: enhancement Stage: needs patch
Components: Versions: Python 3.8
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: Nosy List: eryksun, jcea, nedbat, r.david.murray, serhiy.storchaka, steven.daprano, terry.reedy
Priority: normal Keywords:

Created on 2014-06-01 12:04 by nedbat, last changed 2019-03-20 16:34 by terry.reedy.

Messages (8)
msg219497 - (view) Author: Ned Batchelder (nedbat) * (Python triager) Date: 2014-06-01 12:04
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.
msg219516 - (view) Author: Eryk Sun (eryksun) * (Python triager) Date: 2014-06-01 18:13
> 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)
msg219520 - (view) Author: Ned Batchelder (nedbat) * (Python triager) Date: 2014-06-01 19:42
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"?
msg219547 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2014-06-02 05:20
> 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.
msg219566 - (view) Author: Ned Batchelder (nedbat) * (Python triager) Date: 2014-06-02 10:34
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.
msg219595 - (view) Author: Eryk Sun (eryksun) * (Python triager) Date: 2014-06-02 15:27
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)'
msg219596 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2014-06-02 15:51
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.
msg338493 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2019-03-20 16:34
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.)
History
Date User Action Args
2019-03-20 16:34:36terry.reedysetnosy: + terry.reedy
title: help()'s more-mode is frustrating -> Make help() beginner helpful when no PAGER or LESS variable
messages: + msg338493

type: enhancement
stage: needs patch
2019-02-09 08:00:46steven.dapranosetnosy: + steven.daprano

versions: + Python 3.8, - Python 2.7, Python 3.5
2014-06-19 01:16:47jceasetnosy: + jcea
2014-06-02 15:51:43r.david.murraysetnosy: + r.david.murray
messages: + msg219596
2014-06-02 15:27:53eryksunsetmessages: + msg219595
2014-06-02 10:34:06nedbatsetmessages: + msg219566
2014-06-02 05:20:02serhiy.storchakasetnosy: + serhiy.storchaka
messages: + msg219547
2014-06-01 19:42:46nedbatsetmessages: + msg219520
2014-06-01 18:13:41eryksunsetnosy: + eryksun
messages: + msg219516
2014-06-01 12:04:38nedbatcreate