What should Python apps do when asked to show help?

[Dan Strohl]

I would suggest using argparse https://docs.python.org/3/library/argparse.html as it handles all of that natively... including validating arguments, showing errors, help, etc... however, assuming you don't want to;

Send it to stdout, that allows the user to redirect it if they want to (and plays better with other dev-ops tools)

Don't run it through a pager, the user can do that if needed... HOWEVER
- If you have enough help that you need to page it, consider moving much of it to application documentation (either hosted, or as a doc / txt file).  The command line help should simply be enough hints to remember what the various parameters are, not a full explanation about what it can do (unless the app is really simple).
- Alternatively, you can have a multi-level help approach where the user can type "app_name argument /help" and get more detailed information about that specific argument.


> -----Original Message-----
> From: Python-list [mailto:python-list-bounces+d.strohl=f5.com at python.org]
> On Behalf Of alister
> Sent: Thursday, April 28, 2016 9:45 AM
> To: python-list at python.org
> Subject: Re: What should Python apps do when asked to show help?
> 
> 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
> --
> https://mail.python.org/mailman/listinfo/python-list