[Python-Dev] Python 2.7b1 and argparse's version action

[Tobias Herp]

Hi, all,

(I don't know whether the first attempt to post this went through; I
could'nt find it, so I retry.  My apologies for any inconvenience...)

I noticed that Python 2.7 beta 1 now contains the argparse module, which
might be a good thing.  The code has been cleaned up, too, compared to
the current version 1.1.

But there is still one issue with argparse; to tell the story from the
beginning:

The ArgumentParser class uses uses '-v' as a default short option for
the 'tell me the program version' facility.  Since this is commonly used
for verbosity, and the vast majority of *X commandline tools use '-V'
instead (if they bother to accompany '--version' with a short option at
all).  Therefore I submitted an issue report at

.

To put it short:
*Argparse should simply do this like optparse does already.*
I.e., use '--version', '--help' and '-h' by default, but not '-v'.

Subsequently I spent a hard time arguing.
(Perhaps it was somewhat distracting that I proposed a way of postponing
the creation of the help and version options and to provide them with
the short options which are left unused e.g. for hosts (database
clients), human readability (ls, du, etc.) or verbosity; Steven had
stated it might break backward compatibility if the '-v' option string
for version output would be dropped which might be relied on by other
programs which parse the output.  IMO, however, anyone should be beaten
who relies on '-v' giving the version while '--version' has been present
all the time.  The Zen of Python, 2nd aphorism: "Explicit is better than
implicit")

What happened was the following:
Completely unnecessarily, the 'version' constructor argument is now
deprecated.  This fact doesn't solve any problem I can think of; the
only effect is to make programming more cumbersome, and it is /one more/
difference to optparse.

The 'version' argument is a perfectly reasonable way to provide a script
with a simple version information feature.  Of course, it should only
define the '--version' argument; it *must not* define '-v' for this
purpose, since this is commonly used for verbosity, and '-V' is widely
used to accompany '--version'.  I have lots of scripts which use
optparse, and every single one uses the version argument.  I consider
this a matter of good style.

The deprecation of the 'version' argument press-gangs people to replace
it by
  parser.add_argument('--version', action='version',
  version='',# the only common part
  help="show program's version number and exit")
in every single script (which violates the DRY principle, by the way).

Of course, if a more fancy version information is needed, e.g. reporting
the versions of all imported modules, it is perfectly possible to just
omit the version argument during creation
and build a special 'version' action.  No deprecation warnings are
needed for this.

*Before Python 2.7 reaches productivity stage*, IMNSHO the following
changes should be applied to argparse.py:

- removal of the deprecation warnings
- removal of the default usage of '-v'
  with the version information facility

This is a very simple thing to do; I'd happily provide a patch.
(The only complicated task might be to make the unit tests reflect the
change;  but for a start, 7 lines of the test_main function could be
dropped.)

Just for the records, this is what optparse does:
- it defines -h and --help for the help (unless suppressed)
- it defines --version for the version (if version argument given)
This is how it should be (regarding the version, at least).
This is how the vast majority of *x tools looks like.
No reason to change this behaviour.

What do you think?

-- 

Cheers, Tobias
___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

[Python-Dev] Python 2.7b1 and argparse's version action

[Tobias Herp]

Hi, all,

I noticed that Python 2.7 beta 1 now contains the argparse module, which
might be a good thing.  The code has been cleaned up, too, compared to
the current version 1.1.

But there is still one issue with argparse; to tell the story from the
beginning:

The ArgumentParser class uses uses '-v' as a default short option for
the 'tell me the program version' facility.  Since this is commonly used
for verbosity, and the vast majority of *X commandline tools use '-V'
instead (if they bother to accompany '--version' with a short option at
all).  Therefore I submitted an issue report at

.

To put it short:
*Argparse should simply do this like optparse does already.*
I.e., use '--version', '--help' and '-h' by default, but not '-v'.

Subsequently I spent a hard time arguing.
(Perhaps it was somewhat distracting that I proposed a way of postponing
the creation of the help and version options and to provide them with
the short options which are left unused e.g. for hosts (database
clients), human readability (ls, du, etc.) or verbosity; Steven had
stated it might break backward compatibility if the '-v' option string
for version output would be dropped which might be relied on by other
programs which parse the output.  IMO, however, anyone should be beaten
who relies on '-v' giving the version while '--version' has been present
all the time.  The Zen of Python, 2nd aphorism: "Explicit is better than
implicit")

What happened was the following:
Completely unnecessarily, the 'version' constructor argument is now
deprecated.  This fact doesn't solve any problem I can think of; the
only effect is to make programming more cumbersome, and it is /one more/
difference to optparse.

The 'version' argument is a perfectly reasonable way to provide a script
with a simple version information feature.  Of course, it should only
define the '--version' argument; it *must not* define '-v' for this
purpose, since this is commonly used for verbosity, and '-V' is widely
used to accompany '--version'.  I have lots of scripts which use
optparse, and every single one uses the version argument.  I consider
this a matter of good style.

The deprecation of the 'version' argument press-gangs people to replace
it by
  parser.add_argument('--version', action='version',
  version='',# the only common part
  help="show program's version number and exit")
in every single script (which violates the DRY principle, by the way).

Of course, if a more fancy version information is needed, e.g. reporting
the versions of all imported modules, it is perfectly possible to just
omit the version argument during creation
and build a special 'version' action.  No deprecation warnings are
needed for this.

*Before Python 2.7 reaches productivity stage*, IMNSHO the following
changes should be applied to argparse.py:

- removal of the deprecation warnings
- removal of the default usage of '-v'
  with the version information facility

This is a very simple thing to do; I'd happily provide a patch.
(The only complicated task might be to make the unit tests reflect the
change;  but for a start, 7 lines of the test_main function could be
dropped.)

Just for the records, this is what optparse does:
- it defines -h and --help for the help (unless suppressed)
- it defines --version for the version (if version argument given)
This is how it should be (regarding the version, at least).
This is how the vast majority of *x tools looks like.
No reason to change this behaviour.

What do you think?

-- 

Cheers, Tobias
___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] Python 2.7b1 and argparse's version action

[Tobias Herp]

Ben Finney schrieb:
> Nick Coghlan  writes:
> 
>> I would be a lot happier if argparse as a standard library module just
>> followed optparse's lead here (i.e. defined '--version' only and punted
>> on the shorthand form).
>>
>> To deal with this in a backwards compatible way while remaining on the
>> path to more conventional behaviour, I suggest the following:
>>
>> 1. For Python 2.7, deprecate *just* the "-v" default behaviour for the
>> version. This means "--version" and "-v" will be set to invoke different
>> actions when the version argument is supplied (the latter will trigger a
>> deprecation warning if supplied, while the former will work normally).
>>
>> 2. For Python 3.2, don't create the "-v" shorthand at all (i.e. only
>> create "--version").
> 
> +1
> 
> As someone who uses the existing ‘optparse’ behaviour to implement a
> number of Unix command-line programs, the above all makes more sense for
> ‘argparse’ in the standard library if we're expecting it to be a smooth
> upgrade.

Guys, thanks for your feedback.

Let me see; the suggestion involves the '-v' being set in Python 2.7 by
default, but to another action, which yields a DeprecationWarning /and/
performs the version action, right?

The drawback would be: The '-v' wouldn't be available for other uses.
But I use it all the time (for verbosity).

I don't see why we shouldn't drop the '-v' altogether; where Python
standard libraries are concerned, argparse is a new module, and no
compatibility can be broken; people will expect this to follow the
optparse habits.

Programs developed against former versions of argparse will continue to
work, too; there will just not be a (non-standard) short option
generated, but the long option '--version' will be still there.
Honestly, how frequently do you query program versions?

Unfortunately adding a new '-V' default action /could/ break existing
programs, since people might have worked around the former default; thus
we couldn't do this.

Let's get rid of the default '-v' /now/.  This is clean, this is easy,
it won't break anything (with the possible exception of "prog -v"
version output parsers who deserve no better), and we would be done with it.

-- 
Tobias
___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] Python 2.7b1 and argparse's version action

[Tobias Herp]

Steven Bethard schrieb:
> On Sun, Apr 18, 2010 at 3:31 AM, Tobias Herp  wrote:
>> To put it short:
>> *Argparse should simply do this like optparse does already.*
>> I.e., use '--version', '--help' and '-h' by default, but not '-v'.
> [snip]
>> What happened was the following:
>> Completely unnecessarily, the 'version' constructor argument is now
>> deprecated.
> [snip]
>> The deprecation of the 'version' argument press-gangs people to replace
>> it by
>>  parser.add_argument('--version', action='version',
>>  version='',# the only common part
>>  help="show program's version number and exit")
> 
> What Tobias has conveniently omitted is that there was not much
> agreement on what the default behavior of the version flag should be.

Well, the mail was quite long already, and the issue-tracker issue was
linked.

> Things that were proposed:
> 
> * Use both -v and --version

This is very unusual. I don't know of a single example other than
existing argparse.  Incompatible to existing optparse usage.

> * Use both -V and --version

A very common combination; many programs which support --version
accompany it with -V.
However, if we'd add '-V' to the default option strings, we would likely
break existing programs which worked around the so-far default.

> * Use just --version

IMO the only way, and the way optparse does it.

> * Print out just the version string
> * Print out program name with the version string

If this is an issue:  With optparse, the version argument value is
printed, which is often something like '%prog '+VERSION
(for argparse, '%(prog)s '+VERSION or '%%(prog)s %s' % VERSION).
This way, the decision is left to the programmer.
Completely agreeable, as far as I'm concerned.

> I put up a poll [...]
> 
> Given the lack of consensus, the many
> different options people thought were the "right" way to do things,
> and the fact that the action='version' approach allows people to
> customize the flags to whatever they want, I stick by my decision to
> deprecate the constructor argument ...

A. Very. Bad. Idea.

> ... and redirect people to the more flexible add_argument approach.

It is ok to /allow/ people to customize the flags to whatever they want.
It is /not/ ok to /force/ them to do so, if there is a perfectly
reasonable solution which allows them to stick with their habits.
And there is one: drop the '-v' default.  The only way (see above).

> In the face of ambiguity, refuse the temptation to guess.

No guessing is needed (and the ZoP aphorism is not applicable here: this
is not about guessing what the user might have meant.  Besides, if the
user specifies '--version', [s]he /very/ likely wants some info about
the program version; giving '-v' can have been done looking forward to
--verbose output (ok, nothing bad will happen, but it mismatches user
expectations).

> In general, I should say that I'm not opposed to changing the behavior
> in Python trunk, even if it causes a bit of backwards incompatibility.

A /very little/ bit.
When fetching stdout to get the program version, it is much more
reasonable to rely on '--version' than on '-v'.  This is /the/ option
string which is best supported by far.

> But I'd really like a consensus about the correct behavior, and so far
> I have not seen that.

We'll have one ;-)

-- 
Tobias
___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] Python 2.7b1 and argparse's version action

[Tobias Herp]

Steven Bethard schrieb:
> On Sun, Apr 18, 2010 at 4:03 AM, Nick Coghlan  wrote:
>> To deal with this in a backwards compatible way while remaining on the
>> path to more conventional behaviour, I suggest the following:
>>
>> 1. For Python 2.7, deprecate *just* the "-v" default behaviour for the
>> version. This means "--version" and "-v" will be set to invoke different
>> actions when the version argument is supplied (the latter will trigger a
>> deprecation warning if supplied, while the former will work normally).
> 
> [...]
> 
> All I can imagine you mean is to issue a deprecation warning whenever
> a user of the script provides "-v" at the command line, but that seems
> sketchy to me - we'd be deprecating features of someone's
> *application*, not features of the argparse *library*.

It would raise warnings when the option is /used/ (rather than defined;
such warnings address programmers, though), and it wouldn't free '-v'
for other uses.

I agree that this would be more complicated than necessary.
It would be better to just drop the default usage of '-v'.
This way we wouldn't need a deprecation procedure either.

-- 
Tobias
___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] Python 2.7b1 and argparse's version action

[Tobias Herp]

Eric Smith schrieb:
> Steven Bethard wrote:
>> By the way, we could simplify the typical add_argument usage by adding
>> "show program's version number and exit" as the default help for the
>> 'version' action. Then you should just write:
>>
>> parser.add_argument('--version', action='version', version='> version>')
> 
> I like this the best. I don't like argparse adding arguments for me.

There is no reason why you shouldn't get it.  You could always (and with
optparse as well as argparse) omit the version argument and build or
build not the version argument yourself.

Or a special add_version_option (hey, it's really an /option/) or
add_version_argument method, which would work without if statements and
could be overridden in subclasses.

But note that
- many optparse programs use the version argument
- many other programmers find this feature very convenient
- dropping or deprecating this is a totally unnecessary change
  (I have not read a single real reason /why/ this should be done).

-- 
Tobias
___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] Python 2.7b1 and argparse's version action

[Tobias Herp]

Steven Bethard schrieb:
> On Sun, Apr 18, 2010 at 3:52 PM, Antoine Pitrou  wrote:
>> Steven Bethard  gmail.com> writes:
>>> Note
>>> that even though I agree with you that "-v/--version" is probably not
>>> the best choice, in the poll[2] 11% of people still wanted this.
>>
>> This strikes me as a small minority.
> 
> Agreed, but it's also the current behavior, ...

The current /broken, non-standard/ behaviour.

For keeping a current status quo, this is an even worse poll.  Very
likely some of these voted for this choice because they were afraid of
changes (unnecessarily, as explained before).

> ... and has been since the beginning of argparse.

It's not my fault that in the beginning apparently nobody cared about
existing conventions.

> Note that no one complained about it until
> Tobias filed the issue in Nov 06, 2009.

This is not an argument at all.

I have collected lots of examples of widely used programs and their
options. The only example of '-v', '--verbose' is argparse.
It is vital we meet user expectations, and that we support developers in
producing programs that do so.

-- 
Tobias

___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] Python 2.7b1 and argparse's version action

[Tobias Herp]

Steven Bethard schrieb:
> On Sun, Apr 18, 2010 at 2:35 PM, Tobias Herp  wrote:
>> Steven Bethard schrieb:
>>> On Sun, Apr 18, 2010 at 3:31 AM, Tobias Herp  wrote:
>>>> *Argparse should simply do this like optparse does already.*
>>>> I.e., use '--version', '--help' and '-h' by default, but not '-v'.
>>> [snip]
>>>> The deprecation of the 'version' argument press-gangs people to replace
>>>> it by
>>>>  parser.add_argument('--version', action='version',
>>>>  version='',# the only common part
>>>>  help="show program's version number and exit")
>>>
>>> What Tobias has conveniently omitted is that there was not much
>>> agreement on what the default behavior of the version flag should be.
> [snip a bunch of Tobias's opinions on what the default should be]
>>>
>>> But I'd really like a consensus about the correct behavior, and so far
>>> I have not seen that.
>>
>> We'll have one ;-)
> 
> I hope you can understand that I don't consider your personal opinion
> alone as a consensus.

Be careful.  There have been other personal opinions, and there are very
many *X programs which form a standard which should be followed, and
this is a /very strong/ argument, IMO.

What you conveniently omitted is that I collected a lot of examples and
commented the choices (part of which were part of your poll).
Unfortunately you completely ignored these very prosaic arguments.

By the way, I just had a look at your poll (currently 81 votes).
Correct me if I'm wrong, but...
- AFAICS, you didn't provide your audience with any background
  information, e.g.
  - how optparse does it (and migration should be as easy as possible,
right?)
  - the existing de-facto standard "--version [-V]"
- the choice which reflects my proposal got the most votes
  (46.9% currently)
- 42.0% voted for dropping the version argument, which is a minority
  (bzw., do you really think the 46.9%
  would like the version argument to be deprecated?!)
  which apparently didn't consider the optparse migration/analogy issue.

Furthermore, nobody who dislikes the version feature is forced to use it.
If 60% had voted for removal of a feature which is important and
convenient for 40%, would you remove it?  Really?
IMO, removal of a feature which is used by 40% is out of the question;
and if removal is, deprecation is as well.

Back to the actual numbers: dropping the argument is impossible (/and so
is deprecation/); drop the 42.0%.
Take the remaining numbers: 46.9% voted for the change, and 11.1%
against it.

Do you take your own poll seriously?

-- 
Tobias
___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] Python 2.7b1 and argparse's version action

[Tobias Herp]

Barry Warsaw schrieb:
> On Apr 18, 2010, at 07:30 PM, Eric Smith wrote:
> 
>> Steven Bethard wrote:
>>> By the way, we could simplify the typical add_argument usage by adding
>>> "show program's version number and exit" as the default help for the
>>> 'version' action. Then you should just write:
>>>
>>> parser.add_argument('--version', action='version', version='>> version>')
>>
>> I like this the best. I don't like argparse adding arguments for me.
> 
> I concur.  This gives me all the flexibility I need to make my programs accept
> exactly the arguments I want and print exactly the information I want to
> present.

But you had this possibility all the time!

No deprecation or removal of the simple and convenient 'version'
argument is needed for this.  Just omit it, and build your version
action yourself.  But please notice that there are others who appreciate
this simple way to do it and don't need more.

-- 
Tobias
___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] Python 2.7b1 and argparse's version action

[Tobias Herp]

Nick Coghlan schrieb:
> Tobias Herp wrote:
>> No deprecation or removal of the simple and convenient 'version'
>> argument is needed for this.  Just omit it, and build your version
>> action yourself.  But please notice that there are others who appreciate
>> this simple way to do it and don't need more.
> 
> One Obvious Way.

One /Obvious/ Way!

To simply check off the "give the program a version" task, /this/ (the
version argument) is the way to do it (obvious enough for legions of
programmers who are able to use optparse).  If you need a more fancy
version action, of course, you need to take care of that yourself.

> In this case, the ambiguity of the "version=" argument ...

What /is/ this ambiguity of the "version=" argument? There is none!

Do it the way optparse does it, and all is fine!

-- 
Tobias
___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] Python 2.7b1 and argparse's version action

[Tobias Herp]

"Martin v. Löwis" schrieb:
>> - many optparse programs use the version argument
>> - many other programmers find this feature very convenient
>> - dropping or deprecating this is a totally unnecessary change
>>   (I have not read a single real reason /why/ this should be done).
> 
> You actually brought up a good reason yourself:
> 
> In the face of ambiguity, refuse the temptation to guess.

I didn't guess.  The vast majority of *x commandline tools, *including
the Python interpreter*, uses '--version' and/or '-V' for the version
action, while '-v' is often used for something else, most often
verbosity (again: e.g. the Python interpreter).  Nobody has argued the
converse.  The optparse module uses just '--version' option string by
default, following the standard.

> If you ask "give me a version argument", the question is "how is it
> spelled?". IIUC, you originally complained that the spelling of argparse
> (i.e. -v/--version) is not good, and that a different spelling should be
> used. So it's ambiguous, in which case the feature shouldn't be provided
> in the first place.

Wrong!

Just follow the de-facto standard.  There has never been a problem with
optparse's version argument, simply because of the fact it conforms with
the standard (using just '--version').  Perhaps we wouldn't argue now if
they had decided to add '-V' as well, which is AFAIK /never/ used for
anything else than the version, either;  perhaps this would have been
adopted by argparse as well.  The optik/optparse people didn't, and the
argparse people apparently didn't really look out what options look like
in the wild.

There is *no* problem with a 'version' argument (which has always been
*optional*; nobody is forced to use it) which simply defines the
'--version' option to trigger the version option.  There has *never*
been a problem with the optparse way to do it!

Now argparse wants to become a part of Python's standard library; it
certainly has advantages over optparse.  But the user won't be
interested in the difference:  "Oh, I see, this is an argparse-based
program, so the '-v' is naturally not available for verbosity. Fine!"

Up to today, the argparse module had a limited audience.  When becoming
part of Python, it must follow standards; it should Do The Right Thing
by default, and it should keep the usage difference to optparse as small
as possible.

People should be allowed to rely on the fact that /Python scripts follow
the standards/; this is a huge usability gain.

Thus, argparse should *continue* to support the version argument,
because it is convenient (we use Python because it is convenient!), and
it is sufficient in 95% of the cases (I have written lots of optparse
scripts, and in exactly one case I wrote the version output myself).

It should discontinue the '-v' short option string, because it is
non-standard, and it is ambiguous; it is often used for something else,
while '-V' isn't (but adding this as a default would like break existing
argparse programs, so this is not an option).

If the community feels this is necessary, the '-v' could be supported
'invisibly': it should not be visible in the help, and it must not block
the usage of '-v' for other purposes.

-- 
Tobias
___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com