What should Python apps do when asked to show help?

[cs at zip.com.au]

On 30Apr2016 13:23, Steven D'Aprano <steve at pearwood.info> wrote:
>On Sat, 30 Apr 2016 12:49 pm, Ben Finney wrote:
>> Random832 <random832 at fastmail.com> writes:
>>> On Fri, Apr 29, 2016, at 22:27, Rustom Mody wrote:
>>> > Instead it does some ½-assed fall-between-the-stools of both
>>>
>>> That doesn't answer the question of why, if you (Well, Ethan, but
>>> you're taking the same position here) hate pagers so much
>>
>> That's not a question relevant here; nobody inthe discussion has a
>> position fairly characterised as “hate pagers so much”. So you're
>> arguing against a straw man.
>>
>> Rather, the position being argued is that they *do* like pagers; they
>> like pagers enough that they want the existing ‘PAGER’ environment
>> variable setting to remain untouched.
>
>So they want the PAGER environment variable to specify what pager they
>want...

_When_ they want a pager.

>> And, simulatenously, they want
>> Python's help to not use a pager at the interactive prompt.
>
>...so long as applications don't actually make use of that PAGER environment
>variable to determine the pager they want to use.

_When_ it is asked to use a pager.

What they (and, very often, me) want is that most things, including pydoc, to 
_NOT_ invoke a pager automatically, _unasked_.

So tools which page without asking are unwelcome, because that requires a mode 
switch when everything else (sed/grep/print/write/ls) do straight up unpaged 
output.

>(1) If you want man, and nothing else in the universe, to automatically use
>a pager, then set MANPAGER="less" (or whatever you wish to use), and unset
>PAGER.
>
>(2) If you don't want *anything* to use a pager, then unset both MANPAGER
>and PAGER. You may have to report a feature request / bug report for
>applications which force their own pager.
>
>(3) In Python specifically, you can trivially and easily tell help() to
>output directly to stdout. (At least on Linux, I haven't tested it
>elsewhere.) Simply use PAGER=cat on the command line you use to launch the
>interactive environment. This will affect no other running or future
>processes (apart from subprocesses launched from your interactive Python
>session), allowing you to keep your PAGER for everything else.
>
>(4) If you want more than that, then patches are welcome :-)

This requires terrible domain specific knowledge. What about programs other 
than man?

And setting PAGER=cat before invoking interactive python is no better, because 
it will screw with $PAGER in any subprocess spawned from that environment.

What those of use in the "my terminal emulator scrolls nicely thank you" camp 
want is that most command line things, when asked to simply print some help 
text, _print_ it and do not page it. And often would like a way to tell pydoc 
to not page, such as a pydoc specific switch (possibly an environment 
variable).

>Seriously, I'm thinking that a keyword argument to help might be useful:
>
>help(object, pager=None)
>
>where:
>- pager=None gives the current behaviour;
>- pager="foo" calls out to the external program "foo";
>- pager=callable passes the help text to callable().

I'd be asking for pager=None to look at help.default_pager, which itself might 
obey your rules above. That way help.default_pager can be a callable which 
consults $PAGER or falls back to some inbuilt pager (presumably as now), but 
which a user can sumply go:

  help.default_pager=None

at the Python prompt and have unpaged output from there on.

>I think that would make it easier to test help(). Thoughts?

Yes it would. I'm +1 _provided_ the user can set a global to tune the default 
mode, as otherwise it burdens the user with saying:

  help(foo, stdout.write)   # or "print" ?

whenever they want help. Not helpful!

Let me recite one of my favourite rules of thumb:

  If it can't be turned off, it's not a feature. - Karl Heuer

Cheers,
Cameron Simpson <cs at zip.com.au>