Re: Current thinking on required options
Roel Schroeven writes: > Avi Gross via Python-list schreef op 20/04/2021 om 1:56: >> Sidestepping the wording of "options" is the very real fact that providing >> names for even required parts can be helpful in many cases. > > Very true. It's very much like named arguments in Python function calls: they > help to document precisely and explicitly what's happening, instead of having > to > rely on remembering the order of arguments/options. Thanks to all for the discussion, which I did not think was silly - to me "option" and "optional" are much more closely related than the two meanings of "argument", which, while obviously sharing the same root, have diverged significantly. However, I am grateful for the cpio and tar examples. I'll probably stick with the "required options" and just tweak the usage output of argparse to make it clear that some options are not optional :-) Cheers, Loris -- https://mail.python.org/mailman/listinfo/python-list
Re: Current thinking on required options
Avi Gross via Python-list schreef op 20/04/2021 om 1:56: Sidestepping the wording of "options" is the very real fact that providing names for even required parts can be helpful in many cases. Very true. It's very much like named arguments in Python function calls: they help to document precisely and explicitly what's happening, instead of having to rely on remembering the order of arguments/options. -- "Honest criticism is hard to take, particularly from a relative, a friend, an acquaintance, or a stranger." -- Franklin P. Jones Roel Schroeven -- https://mail.python.org/mailman/listinfo/python-list
RE: Current thinking on required options
Sidestepping the wording of "options" is the very real fact that providing
names for even required parts can be helpful in many cases.
There re programs that may not require anything on the command line to be
done but many need something to provide some flexibility.
So, I tend to agree that in many cases you need an explicit or implicit
argument for a program to do something useful. If I have a simple program
that looks up a phone number when given a name, it would require a name
UNLESS the default behavior is to show ALL entries or repeat whatever I
asked for last time by keeping track or provide the number I ask for most or
pick a random one or return silently having done nothing ...
But I want to point out something OBVIOUS. The requested program in my view
HAS NO required arguments! All are in a sense optional but at the same time
are all mandatory in some circumstances.
It can be called two equally valid ways:
grocli [-h]
OR
grocli -o {check,add,delete} -u USERS [USERS ...]] -g GROUP
When called to ask for help, none of the other arguments are required or are
ignored or worse. When called with the second properly formed set of
arguments, in any order, I assume any "-h" is either ignored or an error.
So I would possibly have TWO usage statements and in both cases, NO optional
arguments! Either you ask for help or you provide everything else.
Clearly your actual code can be designed many ways including allowing all
combinations and throwing in help when asked for in addition to doing what
is requested or allowing multiple -u arguments instead of multiple arguments
following a single -u and so forth. Heck, it can perhaps accept random
additional arguments and pass them along to another command it uses
internally without question in a "..." situation.
So a syntax for defining a program as documentation like the above may need
an OR approach or be even more complex when say two or more arguments can be
used but only ONE is allowed and then it may be mandatory. Picture a -m to
suggest units are metric versus ...
And this "-h" notation is very common in programs and can cause the
description of how a program should be used more complex than it needs to be
if you insist on just one line showing how to use it rather than giving
several valid usages.
-Original Message-
From: Python-list On
Behalf Of Dan Stromberg
Sent: Monday, April 19, 2021 12:04 PM
To: Loris Bennett
Cc: Python List
Subject: Re: Current thinking on required options
On Mon, Apr 19, 2021 at 2:55 AM Loris Bennett
wrote:
> However, the options -o, -u, and -g are required, not optional.
>
> The documentation
>
> https://docs.python.org/3/library/argparse.html#required
>
> advises against required options and here
>
>
> https://stackoverflow.com/questions/24180527/argparse-required-argumen
> ts-listed-under-optional-arguments
>
> a way of adding a section 'required arguments' to the usage is
> described.
>
Of _course_ some options need to be required.
I can't imagine what the author of that page was thinking.
--
https://mail.python.org/mailman/listinfo/python-list
--
https://mail.python.org/mailman/listinfo/python-list
Re: Current thinking on required options
On Mon, Apr 19, 2021 at 12:36 PM Grant Edwards wrote: > On 2021-04-19, Dan Stromberg wrote: > > On Mon, Apr 19, 2021 at 2:55 AM Loris Bennett < > loris.benn...@fu-berlin.de> wrote: > > > >> However, the options -o, -u, and -g are required, not optional. > >> > >> The documentation > >> > >> https://docs.python.org/3/library/argparse.html#required > >> > >> advises against required options and here > >> > >> > >> > https://stackoverflow.com/questions/24180527/argparse-required-arguments-listed-under-optional-arguments > >> > >> a way of adding a section 'required arguments' to the usage is > >> described. > >> > > > > Of _course_ some options need to be required. > > Traditionally, required "things" were called arguments and were not > prefixed with a hyphen. Optional "things" were called options (hence > the similarity in spelling between "optional" and "option"). > This is a silly thread. "option" should be conflated with "optional" no more than "argument" should be conflated with "a logician's disagreement". $ cpio below cmd output started 2021 Mon Apr 19 12:47:07 PM PDT cpio: You must specify one of -oipt options. Try `cpio --help' or `cpio --usage' for more information. Try 'cpio --help' or 'cpio --usage' for more information. $ tar below cmd output started 2021 Mon Apr 19 12:49:47 PM PDT tar: You must specify one of the '-Acdtrux', '--delete' or '--test-label' options Try 'tar --help' or 'tar --usage' for more information. -- https://mail.python.org/mailman/listinfo/python-list
Re: Current thinking on required options
On 2021-04-19, Dan Stromberg wrote: > On Mon, Apr 19, 2021 at 2:55 AM Loris Bennett > wrote: > >> However, the options -o, -u, and -g are required, not optional. >> >> The documentation >> >> https://docs.python.org/3/library/argparse.html#required >> >> advises against required options and here >> >> >> https://stackoverflow.com/questions/24180527/argparse-required-arguments-listed-under-optional-arguments >> >> a way of adding a section 'required arguments' to the usage is >> described. >> > > Of _course_ some options need to be required. Traditionally, required "things" were called arguments and were not prefixed with a hyphen. Optional "things" were called options (hence the similarity in spelling between "optional" and "option"). > I can't imagine what the author of that page was thinking. -- Grant -- https://mail.python.org/mailman/listinfo/python-list
Re: Current thinking on required options
On Tue, Apr 20, 2021 at 4:18 AM Bill Campbell wrote:
>
> On Mon, Apr 19, 2021, Loris Bennett wrote:
> >Hi,
> >
> >I have various small programs which tend to have an interface like the
> >following example:
> >
> > usage: grocli [-h] [-o {check,add,delete}] [-u USERS [USERS ...]] [-g
> > GROUP]
>
> I would do this with the action is first argument.
>
> Usage: grocli check|add|delete [-u USERS ...]
>
Which aligns well with a concept of subcommands (or, in argparse
terms, subparsers).
ChrisA
--
https://mail.python.org/mailman/listinfo/python-list
Re: Current thinking on required options
On Mon, Apr 19, 2021, Loris Bennett wrote:
>Hi,
>
>I have various small programs which tend to have an interface like the
>following example:
>
> usage: grocli [-h] [-o {check,add,delete}] [-u USERS [USERS ...]] [-g GROUP]
I would do this with the action is first argument.
Usage: grocli check|add|delete [-u USERS ...]
Bill
--
INTERNET: b...@celestial.com Bill Campbell; Celestial Software LLC
URL: http://www2.celestial.com/ 6641 E. Mercer Way
Mobile: (206) 947-5591 PO Box 820
Fax:(206) 232-9186 Mercer Island, WA 98040-0820
Force always attracts men of low morality. -- Albert Einstein
--
https://mail.python.org/mailman/listinfo/python-list
Re: Current thinking on required options
On 2021-04-19 16:38:24 -, Jon Ribbens via Python-list wrote: > On 2021-04-19, Paul Bryan wrote: > > Calling them options—when they're required—seems like a problem. 🙂 > > The option is what the value is, not whether there is a value at all. > If you order a coffee then you may have an option as to what temperature > it is, that doesn't mean the coffee having a temperature is optional. No, but you having to specify the temperature is optional. Yoy might order an extra-hot coffee or s luke-warm coffee, but most of the time you will just order a coffee and accept it being at the default temperature. I would agree with others that options should in general be optional. I do break that that rule sometimes, though: If there are several required arguments and they have no obvious natural order, I might use required options for those just to prevent the user (me) from swapping them. hp -- _ | Peter J. Holzer| Story must make more sense than reality. |_|_) || | | | h...@hjp.at |-- Charles Stross, "Creative writing __/ | http://www.hjp.at/ | challenge!" signature.asc Description: PGP signature -- https://mail.python.org/mailman/listinfo/python-list
Re: Current thinking on required options
On 2021-04-19, Paul Bryan wrote: > Calling them options—when they're required—seems like a problem. 🙂 The option is what the value is, not whether there is a value at all. If you order a coffee then you may have an option as to what temperature it is, that doesn't mean the coffee having a temperature is optional. -- https://mail.python.org/mailman/listinfo/python-list
Re: Current thinking on required options
I guess maybe it seems like a problem to someone who hasn't used command line tools much, based solely on a simplistic interpretation of the terminology. But strictly speaking, they're "command line options", or better "command line arguments", not "options". On Mon, Apr 19, 2021 at 9:30 AM Paul Bryan wrote: > Calling them options—when they're required—seems like a problem. 🙂 > > On Mon, 2021-04-19 at 09:04 -0700, Dan Stromberg wrote: > > On Mon, Apr 19, 2021 at 2:55 AM Loris Bennett > wrote: > > However, the options -o, -u, and -g are required, not optional. > > The documentation > > https://docs.python.org/3/library/argparse.html#required > > advises against required options and here > > > > https://stackoverflow.com/questions/24180527/argparse-required-arguments-listed-under-optional-arguments > > a way of adding a section 'required arguments' to the usage is > described. > > > Of _course_ some options need to be required. > > I can't imagine what the author of that page was thinking. > > > -- https://mail.python.org/mailman/listinfo/python-list
Re: Current thinking on required options
Calling them options—when they're required—seems like a problem. 🙂 On Mon, 2021-04-19 at 09:04 -0700, Dan Stromberg wrote: > On Mon, Apr 19, 2021 at 2:55 AM Loris Bennett > > wrote: > > > However, the options -o, -u, and -g are required, not optional. > > > > The documentation > > > > https://docs.python.org/3/library/argparse.html#required > > > > advises against required options and here > > > > > > https://stackoverflow.com/questions/24180527/argparse-required-arguments-listed-under-optional-arguments > > > > a way of adding a section 'required arguments' to the usage is > > described. > > > > Of _course_ some options need to be required. > > I can't imagine what the author of that page was thinking. -- https://mail.python.org/mailman/listinfo/python-list
Re: Current thinking on required options
On Mon, Apr 19, 2021 at 2:55 AM Loris Bennett wrote: > However, the options -o, -u, and -g are required, not optional. > > The documentation > > https://docs.python.org/3/library/argparse.html#required > > advises against required options and here > > > https://stackoverflow.com/questions/24180527/argparse-required-arguments-listed-under-optional-arguments > > a way of adding a section 'required arguments' to the usage is > described. > Of _course_ some options need to be required. I can't imagine what the author of that page was thinking. -- https://mail.python.org/mailman/listinfo/python-list
Re: Current thinking on required options
> On 19 Apr 2021, at 10:57, Loris Bennett wrote:
>
> Hi,
>
> I have various small programs which tend to have an interface like the
> following example:
>
> usage: grocli [-h] [-o {check,add,delete}] [-u USERS [USERS ...]] [-g GROUP]
>
> Command line grouper tool
>
> optional arguments:
>-h, --helpshow this help message and exit
>-o {check,add,delete}, --operation {check,add,delete}
> operation to apply
>-u USERS [USERS ...], --users USERS [USERS ...]
> users to apply operation to
>-g GROUP, --group GROUP
> group to apply operation to
>
> However, the options -o, -u, and -g are required, not optional.
You could use positional args like this:
grocli check user,user group
Barry
>
> The documentation
>
> https://docs.python.org/3/library/argparse.html#required
>
> advises against required options and here
>
>
> https://stackoverflow.com/questions/24180527/argparse-required-arguments-listed-under-optional-arguments
>
> a way of adding a section 'required arguments' to the usage is
> described.
>
> I would be interested to know what the general thinking on "required
> options" is. Is there just a better way of designing such interfaces?
>
> Cheers,
>
> Loris
>
> --
> This signature is currently under construction.
> --
> https://mail.python.org/mailman/listinfo/python-list
>
--
https://mail.python.org/mailman/listinfo/python-list
Re: Current thinking on required options
Gisle Vanem writes:
> Loris Bennett wrote:
>
>>usage: grocli [-h] [-o {check,add,delete}] [-u USERS [USERS ...]] [-g
>> GROUP]
>>
>>Command line grouper tool
>>
>>optional arguments:
>> -h, --helpshow this help message and exit
>> -o {check,add,delete}, --operation {check,add,delete}
>>operation to apply
>> -u USERS [USERS ...], --users USERS [USERS ...]
>>users to apply operation to
>> -g GROUP, --group GROUP
>>group to apply operation to
>>
>> However, the options -o, -u, and -g are required, not optional.
>
> Just a nitpick.
>
> To quote from https://en.wikipedia.org/wiki/Usage_message
> "To indicate required arguments, Angled brackets are
> commonly used, ..."
>
> So then it should better be written as:
> grocli [-h] <-o {check,add,delete}> <-u USERS [USERS ...]> <-g GROUP>
I would take that with a pinch of salt. The Wikipedia page doesn't give
any examples, let alone any that might be considered somehow typical or
representative. Looking at a few tools I use regularly (awk, cat, grep,
sed, ssh, tmux) I couldn't find any which use the angled-bracket
notation. So maybe the notation is not common or just not many programs
have this type of option. The latter would correspond with sentiment in
the argparse documentation that it is an approach to be avoided.
In any case, the usage line is generated automatically by argsparse.
However, I am more interested in what an alternative approach might look
like.
Cheers,
Loris
--
This signature is currently under construction.
--
https://mail.python.org/mailman/listinfo/python-list
Re: Current thinking on required options
On 19/04/2021 11:52, Loris Bennett wrote:
Hi,
I have various small programs which tend to have an interface like the
following example:
usage: grocli [-h] [-o {check,add,delete}] [-u USERS [USERS ...]] [-g GROUP]
Command line grouper tool
optional arguments:
-h, --helpshow this help message and exit
-o {check,add,delete}, --operation {check,add,delete}
operation to apply
-u USERS [USERS ...], --users USERS [USERS ...]
users to apply operation to
-g GROUP, --group GROUP
group to apply operation to
However, the options -o, -u, and -g are required, not optional.
The documentation
https://docs.python.org/3/library/argparse.html#required
advises against required options and here
https://stackoverflow.com/questions/24180527/argparse-required-arguments-listed-under-optional-arguments
a way of adding a section 'required arguments' to the usage is
described.
I would be interested to know what the general thinking on "required
options" is. Is there just a better way of designing such interfaces?
For the example above you could realize the operation through subparsers
and switch group and users. In cases where no such "natural" order of
arguments exists I'd have no qualms to use required options. Personally
I've not yet come across such a case.
--
https://mail.python.org/mailman/listinfo/python-list
Re: Current thinking on required options
Loris Bennett wrote:
usage: grocli [-h] [-o {check,add,delete}] [-u USERS [USERS ...]] [-g GROUP]
Command line grouper tool
optional arguments:
-h, --helpshow this help message and exit
-o {check,add,delete}, --operation {check,add,delete}
operation to apply
-u USERS [USERS ...], --users USERS [USERS ...]
users to apply operation to
-g GROUP, --group GROUP
group to apply operation to
However, the options -o, -u, and -g are required, not optional.
Just a nitpick.
To quote from https://en.wikipedia.org/wiki/Usage_message
"To indicate required arguments, Angled brackets are
commonly used, ..."
So then it should better be written as:
grocli [-h] <-o {check,add,delete}> <-u USERS [USERS ...]> <-g GROUP>
--
--gv
--
https://mail.python.org/mailman/listinfo/python-list
