What should Python apps do when asked to show help?

[alister]

On Fri, 29 Apr 2016 02:33:56 +1000, Steven D'Aprano wrote:

> I have an application written in Python which accepts -h or --help to
> show help. I can:
> 
> (1) print the help text to stdout;
> 
> (2) run the help text through a pager;
> 
> (3) do something else?
> 
> 
> Many command line tools simply output help to stdout (or stderr, if
> they're evil), which makes it easy to redirect the help to a file, pass
> it to grep,
> etc. For example:
> 
> [steve at ando ~]$ wget --help | wc -l 136
> 
> Other tools automatically launch a pager, e.g. man. (Admittedly, man
> --help does not use a pager.) The Python help system, pydoc, does the
> same.
> 
> I was thinking that my application could use pydoc:
> 
> def do_help():
>     import pydoc pydoc.pager(HELPTEXT)
> 
> or just print the help text:
> 
> def do_help():
>     # Do I really need to show this???
>     print(HELPTEXT)
> 
> 
> but I was thinking of doing both: give my application a subcommand or an
> option to display help directly in a pager, while -h and --help print to
> stdout as normal.
> 
> What do you think? Too clever?

Send it to stdout, this gives the user the most choice.

if there is enough that I want it paged then I will pipe it to a pager.

do one job, do it well and don't reinvent the wheel unnecessarily. 



-- 
Nobody shot me.
		-- Frank Gusenberg, his last words, when asked by police
		who had shot him 14 times with a machine gun in the Saint
		Valentine's Day Massacre.

Only Capone kills like that.
		-- George "Bugs" Moran, on the Saint Valentine's Day 
Massacre

The only man who kills like that is Bugs Moran.
		-- Al Capone, on the Saint Valentine's Day Massacre