Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > comp.lang.python > #107807

RE: What should Python apps do when asked to show help?

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> (permalink)
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
X-Trace news.uni-berlin.de sdFqk+zltIyRivf0nQ0cUgxkBkSet8Adn+xPvJlr3sug==
Return-Path <prvs=91944878d=D.Strohl@f5.com>
X-Original-To python-list@python.org
Delivered-To python-list@mail.python.org
X-Spam-Status OK 0.009
X-Spam-Evidence '*H*': 0.98; '*S*': 0.00; 'subject:Python': 0.05; 'subject:help': 0.07; 'stdout': 0.09; 'example:': 0.10; 'python': 0.10; 'output': 0.13; 'thursday,': 0.13; 'def': 0.13; 'suggest': 0.15; 'apps': 0.15; 'argument': 0.15; 'file,': 0.15; 'message-----': 0.15; '(either': 0.16; '--help': 0.16; '2016': 0.16; 'argparse': 0.16; 'argument.': 0.16; 'etc...': 0.16; 'file).': 0.16; 'help?': 0.16; 'received:io': 0.16; 'received:psf.io': 0.16; 'skip:[ 50': 0.16; 'subject:show': 0.16; 'subject:when': 0.16; 'think?': 0.16; 'wrote:': 0.16; 'app': 0.16; 'handles': 0.20; 'to:name:python-list@python.org': 0.20; 'machine': 0.21; 'to:2**1': 0.21; 'assuming': 0.22; 'doc': 0.22; 'pipe': 0.22; 'txt': 0.22; 'pass': 0.22; '(or': 0.23; 'help.': 0.23; 'import': 0.24; 'written': 0.24; 'header:In-Reply-To:1': 0.24; 'command': 0.26; 'bugs': 0.27; 'fri,': 0.27; 'parameters': 0.27; 'accepts': 0.29; 'arguments,': 0.29; 'received:192.168.10': 0.29; 'launch': 0.29; 'asked': 0.29; 'allows': 0.30; 'print': 0.30; 'system,': 0.30; 'that.': 0.30; 'url:mailman': 0.30; 'e.g.': 0.30; 'option': 0.31; 'help,': 0.32; 'run': 0.33; 'url:python': 0.33; "d'aprano": 0.33; 'errors,': 0.33; 'steven': 0.33; 'skip:- 10': 0.34; 'url:listinfo': 0.34; 'gives': 0.35; 'sent:': 0.35; 'could': 0.35; 'text': 0.35; 'something': 0.35; 'subject:': 0.35; 'but': 0.36; 'too': 0.36; 'should': 0.36; 'there': 0.36; 'url:org': 0.36; '(and': 0.36; 'email addr:python.org': 0.36; '(3)': 0.36; 'url:library': 0.36; 'to:addr:python-list': 0.36; 'subject:?': 0.36; 'subject:: ': 0.37; 'really': 0.37; 'display': 0.37; '(2)': 0.37; 'charset:us-ascii': 0.37; 'doing': 0.38; '(1)': 0.38; 'skip:p 20': 0.38; 'does': 0.39; 'application': 0.39; 'enough': 0.39; 'from:': 0.39; 'received:192': 0.39; 'url:mail': 0.40; 'to:addr:python.org': 0.40; 'where': 0.40; 'easy': 0.60; 'url:3': 0.60; 'him': 0.60; 'skip:u 10': 0.61; 'show': 0.62; 'more': 0.63; 'information': 0.63; 'times': 0.63; 'hints': 0.66; 'python-list': 0.66; "they're": 0.66; 'email name:python-list': 0.67; 'day': 0.67; 'frank': 0.72; '+1000,': 0.84; '9:45': 0.84; 'can:': 0.84; 'received:192.168.15': 0.84; 'saint': 0.84; 'to:addr:ntlworld.com': 0.84; 'wheel': 0.84; 'choice.': 0.93; 'man.': 0.93; 'plays': 0.93
DKIM-Signature v=1; a=rsa-sha256; c=simple/simple; d=f5.com; i=@f5.com; q=dns/txt; s=seattle; t=1461862947; x=1493398947; h=from:to:subject:date:message-id:references:in-reply-to: content-transfer-encoding:mime-version; bh=xlT+tn+1ngMsbFjdyX8awjXJqt1iLMCrnHX4x60Nf70=; b=tIeZBi1856GqtBc508q/gqZazXQBci3+7vtm6QtF8WJmaQDj3K4RQIhy v4L3mzYAgoXzXRH8n0uDbybyNol5vovg/J6fMI9nMX0woG1Uy8kOXztT/ QUblOJZ5J8/sp+2Huq/VsvsACFLGxxKOMNxEutstnB1f3LraW08NZ7Xyk 8=;
X-IronPort-AV E=Sophos;i="5.24,547,1454976000"; d="scan'208";a="215389971"
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
X-MS-Has-Attach
X-MS-TNEF-Correlator
x-ms-exchange-transport-fromentityheader Hosted
x-originating-ip [192.168.15.239]
X-BeenThere python-list@python.org
X-Mailman-Version 2.1.22
Precedence list
List-Id General discussion list for the Python programming language <python-list.python.org>
List-Unsubscribe <https://mail.python.org/mailman/options/python-list>, <mailto:python-list-request@python.org?subject=unsubscribe>
List-Archive <http://mail.python.org/pipermail/python-list/>
List-Post <mailto:python-list@python.org>
List-Help <mailto:python-list-request@python.org?subject=help>
List-Subscribe <https://mail.python.org/mailman/listinfo/python-list>, <mailto:python-list-request@python.org?subject=subscribe>
X-Mailman-Original-Message-ID <118360c7f0a4498e8ed35d6dd15b7ac0@seaexchmbx03.olympus.F5Net.com>
X-Mailman-Original-References <57223b76$0$22140$c3e8da3$5496439d@news.astraweb.com> <p6rUy.23471$Sk5.1393@fx45.am4>
Xref csiph.com comp.lang.python:107807

Show key headers only | View raw

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@python.org]
> 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?
> 
> 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@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

Back to comp.lang.python | Previous | Next — Previous in thread | Next in thread | Find similar | Unroll thread

Thread

What should Python apps do when asked to show help? Steven D'Aprano <steve@pearwood.info> - 2016-04-29 02:33 +1000
  Re: What should Python apps do when asked to show help? alister <alister.ware@ntlworld.com> - 2016-04-28 16:45 +0000
    RE: What should Python apps do when asked to show help? Dan Strohl <D.Strohl@F5.com> - 2016-04-28 17:02 +0000
    Re: What should Python apps do when asked to show help? John Wong <gokoproject@gmail.com> - 2016-04-28 13:05 -0400
    RE: What should Python apps do when asked to show help? Dan Strohl <D.Strohl@F5.com> - 2016-04-28 17:25 +0000
    Re: What should Python apps do when asked to show help? Ethan Furman <ethan@stoneleaf.us> - 2016-04-28 10:27 -0700
  Re: What should Python apps do when asked to show help? Ethan Furman <ethan@stoneleaf.us> - 2016-04-28 09:49 -0700
  Re: What should Python apps do when asked to show help? Chris Angelico <rosuav@gmail.com> - 2016-04-29 03:06 +1000
  Re: What should Python apps do when asked to show help? Irmen de Jong <irmen.NOSPAM@xs4all.nl> - 2016-04-28 19:08 +0200
    Re: What should Python apps do when asked to show help? Marko Rauhamaa <marko@pacujo.net> - 2016-04-28 20:31 +0300
      Re: What should Python apps do when asked to show help? Gregory Ewing <greg.ewing@canterbury.ac.nz> - 2016-04-29 18:04 +1200
    RE: What should Python apps do when asked to show help? Dan Strohl <D.Strohl@F5.com> - 2016-04-28 17:32 +0000
  Re: What should Python apps do when asked to show help? Jussi Piitulainen <jussi.piitulainen@helsinki.fi> - 2016-04-28 20:30 +0300
  Re: What should Python apps do when asked to show help? Random832 <random832@fastmail.com> - 2016-04-28 13:30 -0400
  Re: What should Python apps do when asked to show help? Grant Edwards <grant.b.edwards@gmail.com> - 2016-04-28 17:33 +0000
  RE: What should Python apps do when asked to show help? Dan Strohl <D.Strohl@F5.com> - 2016-04-28 17:39 +0000
  Re: What should Python apps do when asked to show help? Random832 <random832@fastmail.com> - 2016-04-28 13:40 -0400
  Re: What should Python apps do when asked to show help? Grant Edwards <grant.b.edwards@gmail.com> - 2016-04-28 18:14 +0000
    Re: What should Python apps do when asked to show help? Marko Rauhamaa <marko@pacujo.net> - 2016-04-28 21:31 +0300
      Re: What should Python apps do when asked to show help? Grant Edwards <grant.b.edwards@gmail.com> - 2016-04-28 19:39 +0000
      Re: What should Python apps do when asked to show help? Random832 <random832@fastmail.com> - 2016-04-28 15:51 -0400
      Re: What should Python apps do when asked to show help? Grant Edwards <grant.b.edwards@gmail.com> - 2016-04-28 21:08 +0000
        Re: What should Python apps do when asked to show help? Steven D'Aprano <steve@pearwood.info> - 2016-04-29 11:40 +1000
          manpage writing [rst, asciidoc, pod] was [Re: What should Python apps do when asked to show help?] "Martin A. Brown" <martin@linux-ip.net> - 2016-04-29 06:32 -0700
          Re: manpage writing [rst, asciidoc, pod] was [Re: What should Python apps do when asked to show help?] Ethan Furman <ethan@stoneleaf.us> - 2016-04-29 07:06 -0700
            Re: manpage writing [rst, asciidoc, pod] was [Re: What should Python apps do when asked to show help?] Rustom Mody <rustompmody@gmail.com> - 2016-04-29 08:17 -0700
          Re: manpage writing [rst, asciidoc, pod] was [Re: What should Python apps do when asked to show help?] Ben Finney <ben+python@benfinney.id.au> - 2016-04-30 12:25 +1000
            Re: manpage writing [rst, asciidoc, pod] was [Re: What should Python apps do when asked to show help?] Rustom Mody <rustompmody@gmail.com> - 2016-04-29 20:20 -0700
              Re: manpage writing [rst, asciidoc, pod] was [Re: What should Python apps do when asked to show help?] Paul Rubin <no.email@nospam.invalid> - 2016-04-29 21:06 -0700
                Re: manpage writing [rst, asciidoc, pod] was [Re: What should Python apps do when asked to show help?] Rustom Mody <rustompmody@gmail.com> - 2016-04-29 23:37 -0700
                Re: manpage writing [rst, asciidoc, pod] was [Re: What should Python apps do when asked to show help?] Paul Rubin <no.email@nospam.invalid> - 2016-04-30 00:44 -0700
          Writing manual pages using Python code (was: manpage writing) Ben Finney <ben+python@benfinney.id.au> - 2016-04-30 12:25 +1000
          Re: What should Python apps do when asked to show help? cs@zip.com.au - 2016-05-01 10:06 +1000
  Re: What should Python apps do when asked to show help? Paul Rubin <no.email@nospam.invalid> - 2016-04-28 19:15 -0700
    Re: What should Python apps do when asked to show help? Rustom Mody <rustompmody@gmail.com> - 2016-04-28 22:00 -0700
      Re: What should Python apps do when asked to show help? Jussi Piitulainen <jussi.piitulainen@helsinki.fi> - 2016-04-29 09:02 +0300
      Re: What should Python apps do when asked to show help? Steven D'Aprano <steve@pearwood.info> - 2016-04-29 19:36 +1000
        Re: What should Python apps do when asked to show help? Rustom Mody <rustompmody@gmail.com> - 2016-04-29 02:53 -0700
          Re: What should Python apps do when asked to show help? Steven D'Aprano <steve@pearwood.info> - 2016-04-30 11:20 +1000
            Re: What should Python apps do when asked to show help? Ethan Furman <ethan@stoneleaf.us> - 2016-04-29 19:09 -0700
            Re: What should Python apps do when asked to show help? Random832 <random832@fastmail.com> - 2016-04-29 22:16 -0400
              Re: What should Python apps do when asked to show help? Rustom Mody <rustompmody@gmail.com> - 2016-04-29 19:27 -0700
                Re: What should Python apps do when asked to show help? Random832 <random832@fastmail.com> - 2016-04-29 22:36 -0400
                Re: What should Python apps do when asked to show help? Rustom Mody <rustompmody@gmail.com> - 2016-04-29 19:46 -0700
                Re: What should Python apps do when asked to show help? Random832 <random832@fastmail.com> - 2016-04-29 23:14 -0400
                Re: What should Python apps do when asked to show help? Ben Finney <ben+python@benfinney.id.au> - 2016-04-30 12:49 +1000
                Re: What should Python apps do when asked to show help? Steven D'Aprano <steve@pearwood.info> - 2016-04-30 13:23 +1000
                Re: What should Python apps do when asked to show help? Ben Finney <ben+python@benfinney.id.au> - 2016-04-30 14:06 +1000
                Re: What should Python apps do when asked to show help? Random832 <random832@fastmail.com> - 2016-04-30 00:16 -0400
                Re: What should Python apps do when asked to show help? Rustom Mody <rustompmody@gmail.com> - 2016-04-29 21:34 -0700
                Re: What should Python apps do when asked to show help? Random832 <random832@fastmail.com> - 2016-04-30 01:20 -0400
                Re: What should Python apps do when asked to show help? cs@zip.com.au - 2016-05-01 09:51 +1000
                Re: What should Python apps do when asked to show help? Steven D'Aprano <steve@pearwood.info> - 2016-05-01 14:28 +1000
                Re: What should Python apps do when asked to show help? Random832 <random832@fastmail.com> - 2016-04-30 20:41 -0400
                Re: What should Python apps do when asked to show help? Grant Edwards <grant.b.edwards@gmail.com> - 2016-05-01 02:30 +0000
                Re: What should Python apps do when asked to show help? Random832 <random832@fastmail.com> - 2016-04-30 23:46 -0400

csiph-web