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

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

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 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

Steven Bethard writes:

I need to a see a consensus from a variety of developers that "--version" is the right answer, and not "-V/--version", etc.

Both are ok for me. "-v" as a shortcut for "--version" looks wrong, though. "-v" is almost always used for verbosity these days.

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. Regards Antoine.

On Sun, Apr 18, 2010 at 3:52 PM, Antoine Pitrou wrote:

Steven Bethard 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, and has been since the beginning of argparse. Note that no one complained about it until Tobias filed the issue in Nov 06, 2009. Steve -- Where did you get that preposterous hypothesis? Did Steve tell you that? --- The Hiphopopotamus

Tobias Herp writes:

Steven Bethard schrieb:

...

On Sun, Apr 18, 2010 at 3:52 PM, Antoine Pitrou wrote:

...

Steven Bethard 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.

I think that is overstating your case. Steven is pointing out the fact that “default to ‘-v’ and ‘--version’” is the current behaviour for argparse. It's also a fact that argparse, as a third-party library, has an existing user base, and changing this behaviour incompatibly is not something to do lightly. To call this behaviour “broken” is a stretch too far, IMO. It does break compatibility with optparse, but it's not *inherently* broken as the above would imply. Nor is there really a standard for this behaviour to be measured “non-standard”. At best, there is a strong convention among Unix command-line programs of ‘--version’ for a version action and ‘-v’ for enabling verbose output. But that convention is not normative, so it's too much to call it a standard IMO.

I have collected lots of examples of widely used programs and their options. The only example of '-v', '--verbose' is argparse.

I'm not sure what programs you're talking about (argparse is a library, not a program that can be run by itself), but in a brief search of my system I've found several programs that use ‘-v’ for a version action, including among others: * Info-ZIP's ‘zip’ and ‘unzip’ * GNU ‘fdisk’ * Vim's ‘xxd’ * W3C's ‘tidy’ These are certainly widely deployed, although they may not be widely familiar. I do agree that such programs are a small minority, but it's overstating your case to call them “non-standard”, since there's no standard for this, or “broken”, since they demonstrably work fine. Rather, they buck what is certainly a firm convention to avoid ‘-v’ for a version option. I'm certainly in favour of preserving that convention by avoiding use of ‘-v’ for version. I would rather, though, that the discussion remain aware of facts and not descend into hyperbole. -- \ “Perchance you who pronounce my sentence are in greater fear | `\ than I who receive it.” —Giordano Bruno, burned at the stake by | _o__) the Catholic church for the heresy of heliocentrism, 1600-02-16 | Ben Finney

On Sun, Apr 18, 2010 at 7:02 PM, Ian Bicking wrote:

Somewhat relatedly, what is the plan for past and future argparse releases?

I currently don't have any plans to make releases outside of the main Python releases. Perhaps if there's great demand for it, I'll reconsider, but as it is, I haven't had as much time as I would like for argparse, and managing two different types of releases is probably unrealistic for me at the moment. Steve -- Where did you get that preposterous hypothesis? Did Steve tell you that? --- The Hiphopopotamus

Cameron Simpson wrote:

On 18Apr2010 22:52, Antoine Pitrou wrote: | Steven Bethard writes: | > I | > need to a see a consensus from a variety of developers that | > "--version" is the right answer, and not "-V/--version", etc. | | Both are ok for me. "-v" as a shortcut for "--version" looks wrong, though. | "-v" is almost always used for verbosity these days.

My view is the same.

I don't expect -v to be one or the other, and I certainly don't expect the rest of the world to want to confirm to what the Python community decides. regards Steve -- Steve Holden +1 571 484 6266 +1 800 494 3119 See PyCon Talks from Atlanta 2010 http://pycon.blip.tv/ Holden Web LLC http://www.holdenweb.com/ UPCOMING EVENTS: http://holdenweb.eventbrite.com/

On Sun, Apr 18, 2010 at 3:57 PM, Nick Coghlan 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='<the version>')

With that change, I would have no problem with the current argparse behaviour (since doing it this way makes it very easy for people to add a "-V" shortcut if they want one).

Probably this should happen regardless of the outcome of the constructor argument. The only reason it wasn't already there is that I hadn't thought of it. ;-) Steve -- Where did you get that preposterous hypothesis? Did Steve tell you that? --- The Hiphopopotamus

On 04/18/2010 06:35 PM, Nick Coghlan wrote:

Steven Bethard wrote:

...

On Sun, Apr 18, 2010 at 3:57 PM, Nick Coghlan 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='<the version>') With that change, I would have no problem with the current argparse behaviour (since doing it this way makes it very easy for people to add a "-V" shortcut if they want one).

Probably this should happen regardless of the outcome of the constructor argument. The only reason it wasn't already there is that I hadn't thought of it. ;-)

Crazy thought... would it make sense to have the following implicitly use "--version" as the option flag:

parser.add_argument(action='version', version='<details>')

There are two things about the explicit '--version' that bother me: 1. It reduces the automatic provision of "standard" option spellings

I think any non standard spellings will either be on purpose or be caught fairly quickly. And in either case I can't imagine it having an impact on the rest of the program, so I wouldn't worry about this too much.

2. The repetition in reading/writing 'version' 3 times is kind of annoying

Ahh, but it isn't the same exact 'version' each time. One is an input specifier string, one is an action key, and the last is a value name.

(Probably a bad idea, since adding "-V" would mean having to add "--version" as well, but figured it was worth mentioning).

I agree. Even though it may seem redundant when writing it, it's both clear and explicit when reading it even if you aren't very familiar with how argparse works, or have just returned from a really long and fun vacation. ;-) Ron

On 04/18/2010 05:57 PM, Nick Coghlan 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='<the version>')

With that change, I would have no problem with the current argparse behaviour (since doing it this way makes it very easy for people to add a "-V" shortcut if they want one).

+1 This sounds good to me also. Note that the python interpreter uses -V and --version. ra@Gutsy:~$ python3.1 -V Python 3.1.2 ra@Gutsy:~$ python3.1 --version Python 3.1.2 And -v is used as follows: -v : verbose (trace import statements); also PYTHONVERBOSE=x can be supplied multiple times to increase verbosity Ron

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='<the version>')

I like this the best. I don't like argparse adding arguments for me. Eric.

- 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. 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. Regards, Martin

Tobias Herp writes:

(we use Python because it is convenient!),

Speak for yourself, I want no part of that "we". I use Python because it's well defined and well documented and makes sense and provides powerful operations and runs quickly enough in those applications where I use it. The fact that it's not excessively inconvenient despite an avowed bias toward EIBTI is the icing, not the cake. Remember, convenience is explicitly subsidiary: "not every 3 line function needs to be a builtin." I have no particular opinion the rest of the debate.

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='<the 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

Nick Coghlan wrote:

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.

In this case, the ambiguity of the "version=" argument is sufficient to elevate it to the level of "attractive nuisance" (particularly given the legacy behaviour of conflicting with typical verbosity options). The default help for the action needs to be fixed, and there are a couple of documentation tweaks to be made, but Steven's decision to remove the feature has a sound rationale.

Exactly my feelings. IMO, straight removal would be fine as well, but a deprecation may be more user-friendly, wrt. the existing code base. Regards, Martin

Tobias Herp wrote:

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

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

All is not fine. How do I add a "-V" shortcut that is equivalent to "--version" as part of an optparse program? (That's a real question, I honestly have no idea how I would do that short of writing my own version display option). Since argparse now uses action='version' instead, the same question becomes trivial (just list "-V" as one of the accepted options for that action). There are at least three reasonable approaches for version options (ignoring the fact that Windows users expect their options to start with a '/' instead of a '-'): - just "--version" (the optparse way) - "-V" and "--version" (the Python interpreter way) - "-v" and "--version" (the old argparse way) The third is by far the least common of the three, but even you admit both of the first two are quite common and acceptable according to the de facto "standard". Optparse makes it easy to do it the optparse way, but difficult to support either of the other formats. Argparse used to be in a similar boat, where only the third option was easy. The latest argparse approach is straightforward regardless of the particular spelling you happen to prefer. Since getting away from the "thou shalt" preachiness of optparse is one of the big reasons for adding argparse in the first place, it seems odd to complain when it switches to a more consistent and flexible API. There were a couple of issues to be addressed with the implementation and the documentation, but the basic approach is sound. Cheers, Nick. -- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia ---------------------------------------------------------------

Tobias Herp wrote:

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.

If the "version=" argument were to only provide "--version", how would you conveniently add a "-V" shorthand? This is trivial with the add_argument approach, but less straightforward with a "version=" argument to the parser constructor. People that want "-v" to mean verbosity in 2.x can also trivially pass "conflict_handler='resolve'" to override the implicitly created version shorthand. Would it be more convenient if argparse had never deviated from the GNU and optparse command line conventions in this respect? Sure it would be. But given that it did, a 'version' action that makes it trivial to choose the details of your version flags is a decent alternative approach to a now-ambiguous version argument to the parser constructor (especially once the default help string for the option is added). Note there are two changes I believe should be made to the argparse documentation for 2.7 though: - the '--version' example should either not use a shorthand, or should use the conventional '-V' - this issue needs to be mentioned in the section on migrating from optparse. Cheers, Nick. -- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia ---------------------------------------------------------------

Tobias Herp wrote:

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 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?

When was this ever a democracy? regards Steve -- Steve Holden +1 571 484 6266 +1 800 494 3119 See PyCon Talks from Atlanta 2010 http://pycon.blip.tv/ Holden Web LLC http://www.holdenweb.com/ UPCOMING EVENTS: http://holdenweb.eventbrite.com/

On 19/04/2010 21:19, Scott Dial wrote:

On 4/18/2010 9:44 PM, Steve Holden wrote:

...

Tobias Herp wrote:

...

Steven Bethard schrieb:

...

On Sun, Apr 18, 2010 at 2:35 PM, Tobias Herp wrote:

...

Steven Bethard schrieb:

...

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

Do you take your own poll seriously?

When was this ever a democracy?

Is consensus superficial?

No, but it isn't always possible or necessary. In general the maintainer of a module should make the best decision, not the one with the most backing. :-) All the best, Michael -- http://www.ironpythoninaction.com/