Path: csiph.com!fu-berlin.de!uni-berlin.de!not-for-mail
From: Dan Strohl <D.Strohl@F5.com>
Newsgroups: comp.lang.python
Subject: RE: What should Python apps do when asked to show help?
Date: Thu, 28 Apr 2016 17:02:23 +0000
Lines: 88
Message-ID: <mailman.197.1461862948.32212.python-list@python.org>
References: <57223b76$0$22140$c3e8da3$5496439d@news.astraweb.com> <p6rUy.23471$Sk5.1393@fx45.am4> <118360c7f0a4498e8ed35d6dd15b7ac0@seaexchmbx03.olympus.F5Net.com>
Mime-Version: 1.0
Content-Type: text/plain; charset="us-ascii"
Content-Transfer-Encoding: quoted-printable
Thread-Topic: What should Python apps do when asked to show help?
Thread-Index: AQHRoWw0yo/CeHHw+k+f9dhTV82UOp+fmahCgAAAytA=
In-Reply-To: <p6rUy.23471$Sk5.1393@fx45.am4>
Accept-Language: en-US
Content-Language: en-US
Precedence: list
Xref: csiph.com comp.lang.python:107807

I would suggest using argparse https://docs.python.org/3/library/argparse.h=
tml as it handles all of that natively... including validating arguments, s=
howing 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 va=
rious parameters are, not a full explanation about what it can do (unless t=
he app is really simple).
- Alternatively, you can have a multi-level help approach where the user ca=
n type "app_name argument /help" and get more detailed information about th=
at specific argument.


> -----Original Message-----
> From: Python-list [mailto:python-list-bounces+d.strohl=3Df5.com@python.or=
g]
> On Behalf Of alister
> Sent: Thursday, April 28, 2016 9:45 AM
> To: python-list@python.org
> Subject: Re: What should Python apps do when asked to show help?
>=20
> On Fri, 29 Apr 2016 02:33:56 +1000, Steven D'Aprano wrote:
>=20
> > 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@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?
>=20
> Send it to stdout, this gives the user the most choice.
>=20
> if there is enough that I want it paged then I will pipe it to a pager.
>=20
> do one job, do it well and don't reinvent the wheel unnecessarily.
>=20
>=20
>=20
> --
> 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.
>=20
> Only Capone kills like that.
> 		-- George "Bugs" Moran, on the Saint Valentine's Day
> Massacre
>=20
> 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