[issue25314] Documentation: argparse's actions store_{true, false} default to False/True (undocumented)
New submission from Julien Baley: The documentation of the action `store_const` states that it defaults to None. In turn, the documentation of `store_true` and `store_false` states that "[t]hese are special cases of 'store_const'", suggesting that they would also default to None. Thankfully, `store_true` defaults to False and `store_false` to True, but this is not documented. That would be useful, as I keep seeing people writing `action='store_true' default=False` and vice-versa. ---------- assignee: docs@python components: Documentation files: store_true_false_doc.patch keywords: patch messages: 252288 nosy: Julien Baley, docs@python priority: normal severity: normal status: open title: Documentation: argparse's actions store_{true,false} default to False/True (undocumented) type: enhancement Added file: http://bugs.python.org/file40676/store_true_false_doc.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue25314> _______________________________________
R. David Murray added the comment: There is another issue to fix the documentation for store_const, which does not in fact default to anything. The 'default" in this case is the default for the value stored when the option is specified. So if store_true also implies 'default=False', that should indeed be documented. ---------- nosy: +r.david.murray _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue25314> _______________________________________
Julien Baley added the comment: That's true, store_const has no default and will throw an exception if const is not provided. Updated the patch consequently. ---------- Added file: http://bugs.python.org/file40677/store_const_true_false_doc.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue25314> _______________________________________
Changes by Julien Baley <julien.baley@gmail.com>: Removed file: http://bugs.python.org/file40676/store_true_false_doc.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue25314> _______________________________________
paul j3 added the comment: I have seen questions on StackOverflow with 'store_true' and explicit `default=False` parameters. I don't recall any where this was a problem. Usually it's as harmless as users specifying other defaults like `action='store'`, or a dest that echos a long option, etc. But if we are going to fix the wrong default statement in `store_const`, we might as well clarify this case as well. I wonder if this is the time and place to add a note that specifying 'type' is not necessary (and even wrong) - re. this closed issue: http://bugs.python.org/issue24754 Is the line 'These are special cases of ``'store_const'``' useful? The statement echos the class definition class _StoreTrueAction(_StoreConstAction) but I'm not sure it adds much to the user's understanding. 'store_true' and 'store_false' are used frequently; 'store_const' is much less common (based on SO questions). ---------- nosy: +paul.j3 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue25314> _______________________________________
Julien Baley added the comment: This issue has now been open for nearly three months. I think my patch is an improvement over the current documentation. If people want to improve the documentation further, they can probably submit a patch for that. What can I do to get this accepted? ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue25314> _______________________________________
Georg Brandl added the comment: Hi Julien, thanks for your patch and sorry for the lack of reviews. I find the new wording in the second hunk confusing: ``'store_true'`` and ``'store_false'`` - These store the values ``False`` respectively (Note that these default to ``False`` and ``True`` respectively). These are special cases of ``'store_const'``. On first read, It seems to contradict itself. I know what is meant, but I think it should be expanded a bit. Also, the part about ``store_const`` should still mention the default for its value (not for the const). I suppose it's ``None``? ---------- nosy: +georg.brandl _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue25314> _______________________________________
Julien Baley added the comment: Hi Georg, thanks for your answer. I think maybe you're missing a bit in there? "``'store_true'`` and ``'store_false'`` - These store the values ``True`` and ``False`` respectively (Note that these default to ``False`` and ``True`` respectively). These are special cases of ``'store_const'``." (added "``True`` andd") But if I'm correct, you're talking of the parenthesis which would be confusing? Can we come up with a better wording? "(and default to False and True if the action is not triggered)" ? As for `store_const`, R. David Murray says it has no default. It is technically correct: store_const behaves like any other action in that it defaults to whatever the argument `default` in `add_argument` is set to. The fact that `default` defaults to None is indicated in 16.4.3.5. default: "The default keyword argument of add_argument(), whose value defaults to None," Therefore, I believe it is more correct the way R. David Murray suggested. What do you think? ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue25314> _______________________________________
paul j3 added the comment: How about: These store the values True and False respectively (and default to False and True if absent). The reference to `store_const` is confusing, since almost no one uses that action. The `store_const` paragraph has: (Note that the const keyword argument defaults to the rather unhelpful None.) But the most common `store` action also defaults to the default default None. In fact most action types do that. With 'store' action, None is a useful default, since its impossible to provide in the commandline. Thus if args.foo is None: is a clear test that 'foo' was not present in the commandline. I can imagine using the same test on a 'store_const' argument (though I've never had the need to use it or recommend it). I'm almost of the opinion that we should remove that parenthetical remark. The 'const' parameter is used most often with 'store' and "nargs='?'", as illustrated in that 'nargs' subsection. To complicate things, if I provide a "argument_default='boo'" parameter in the parser definition, it overrides all of these default defaults, including for 'store_true'. In that case an explicit 'default=False' is *required*, not superfluous. To further complicate things, 'parser.set_defaults' can override all of these. We've almost given users too many ways of setting 'default'. :) Fortunately in practice they don't use most of them. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue25314> _______________________________________
Martin Panter added the comment: I definitely agree with removing the remark about the “const” value with store_const. People here seem to be overloading the terms “default” and “argument”. When using store_const, it seems the programmer must also specify a value for the “const” parameter to add_argument(). It is incorrect to say it is None if not explicitly set. On the other hand, I think if the end user omits a CLI argument configured with store_const, then the argparse module will substitute None, or the value of the “default” parameter to add_argument(). For the original report about store_true/false, perhapse it would be sufficient to port revision 49677cc6d83a to Python 3. Although there is a stray “using” that should probably be fixed. ---------- nosy: +martin.panter versions: +Python 2.7, Python 3.5, Python 3.6 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue25314> _______________________________________
Julien Baley added the comment: I like paul.j3's suggestion, but it would probably make more sense to have it consistent with python2 and port the change Martin pointed to. How does one do that? ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue25314> _______________________________________
Roundup Robot added the comment: New changeset 566fe3564684 by Raymond Hettinger in branch '3.5': Issue #25314: store_true and store_false also create appropriate defaults. https://hg.python.org/cpython/rev/566fe3564684 New changeset 9fdeca5fdbf0 by Martin Panter in branch 'default': Issue #25314: Merge argparse doc from 3.5 https://hg.python.org/cpython/rev/9fdeca5fdbf0 ---------- nosy: +python-dev _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue25314> _______________________________________
Martin Panter added the comment: For the record, porting the change was rather easy (hg graft + tweak + hg commit --amend). With that applied, I think it eliminates the need for the store_true/false half of Julien’s patch. Is the store_const half of Julien’s patch ready to commit? ---------- stage: -> patch review _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue25314> _______________________________________
Martin Panter added the comment: Patch with the outstanding change for const, plus an extra fix under the main description. ---------- Added file: http://bugs.python.org/file42407/store_const.v2.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue25314> _______________________________________
Changes by Martin Panter <vadmium+py@gmail.com>: Removed file: http://bugs.python.org/file42407/store_const.v2.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue25314> _______________________________________
Changes by Martin Panter <vadmium+py@gmail.com>: Added file: http://bugs.python.org/file42408/store_const.v2.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue25314> _______________________________________
Roundup Robot added the comment: New changeset c42a9233af04 by Martin Panter in branch '2.7': Issue #25314: Remove confused statement about const argument https://hg.python.org/cpython/rev/c42a9233af04 New changeset 59b8db278e3c by Martin Panter in branch '3.5': Issue #25314: Remove confused statement about const argument https://hg.python.org/cpython/rev/59b8db278e3c New changeset 7d61a991f405 by Martin Panter in branch 'default': Issue #25314: Merge argparse doc from 3.5 https://hg.python.org/cpython/rev/7d61a991f405 ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue25314> _______________________________________
Changes by Martin Panter <vadmium+py@gmail.com>: ---------- resolution: -> fixed stage: patch review -> resolved status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue25314> _______________________________________
participants (6)
-
Georg Brandl -
Julien Baley
-
Martin Panter
-
paul j3
-
R. David Murray
-
Roundup Robot