bpo-21150: Add summary of argparse by louisom · Pull Request #1210 · python/cpython

louisom · 2017-04-20T06:04:40Z

No description provided.

mention-bot · 2017-04-20T06:04:42Z

@lulouie, thanks for your PR! By analyzing the history of the files in this pull request, we identified @benjaminp, @birkenfeld and @ezio-melotti to be potential reviewers.

merwok · 2017-09-27T19:01:11Z

+^^^^^^^^^^^^^
+
+.. csv-table::
+ :header: "Name", "Common Used Arguments", "Example"


merwok · 2017-09-27T19:01:52Z

+
+ ":class:`argparse.ArgumentParser`", "`prog`_, `description`_, `formatter_class`_", "``parser = argparse.ArgumentParser(prog='PROG', description='DESC', formatter_class=argparse.RawDescriptionHelpFormatter)``"
+ ":func:`ArgumentParser.add_argument`", "`name or flags`_, `action`_, `default`_, `type`_, `required`_, `help`_", "``parser.add_argument('-v', '--verbose', action='store_true', help='Show various debugging information')``"
+


Why not have two small code blocks rather than a table here?

With a code block it is not possible to link to the individual args, but I'm not sure that's really necessary since there are already links in one of the following tables.

merwok · 2017-09-27T19:04:53Z

+.. _prog:
+
 prog
 ^^^^


I think the target markup is not necessary. The headings are automatically targets, but the markup to create the link is different (if I remember right):
`:ref:`prog`

ezio-melotti · 2017-10-13T12:55:00Z

+`const`_ The constant values of name or flags
+`choices`_ Arguments should selected from this set or values ``['foo', 'bar']``, ``range(1, 10)``, Any object that support ``in`` operator
+`required`_ Indicate a optional argument is required or not ``True``, ``False``
+`metavar`_ A alternative display name for argument


ezio-melotti · 2017-10-13T12:57:40Z

+====================== ================================================== =======================================================================================================================
+Name Description Keywords
+====================== ================================================== =======================================================================================================================
+`nargs`_ Associates number of arguments ``N`` (an integer), ``'?'``, ``'*'``, ``'+'``, ``argparse.REMAINDER``


This description is not particularly clear.
You should also decide if you want to use 2nd or 3rd person and do it consistently (e.g. this is 3rd, but then you have "indicate" which is 2nd/imperative).
You could use :class:`int` instead of integer.

ezio-melotti · 2017-10-13T12:58:27Z

+`nargs`_ Associates number of arguments ``N`` (an integer), ``'?'``, ``'*'``, ``'+'``, ``argparse.REMAINDER``
+`const`_ The constant values of name or flags
+`choices`_ Arguments should selected from this set or values ``['foo', 'bar']``, ``range(1, 10)``, Any object that support ``in`` operator
+`required`_ Indicate a optional argument is required or not ``True``, ``False``


ezio-melotti · 2017-10-13T12:59:57Z

+====================== =============================================== =========================================================================================================================
+Name Description Keywords
+====================== =============================================== =========================================================================================================================
+`action`_ What to do on arguments ``'store'``, ``'store_const'``, ``'store_true'``, ``'append'``, ``append_const``, ``count``, ``help``, ``version``


Maybe s/on/with the/?
The last few values are missing the quotes.

ezio-melotti · 2017-10-13T13:01:18Z

+`action`_ What to do on arguments ``'store'``, ``'store_const'``, ``'store_true'``, ``'append'``, ``append_const``, ``count``, ``help``, ``version``
+`default`_ Default value of arguments
+`type`_ Treat arguments as type ``int``, ``float``, ``bool``, ``argparse.FileType('w')``, ``callable function``
+`help`_ Help message of arguments


I would use singular "argument" throughout the table, since add_argument and its options only affect a single argument.

ezio-melotti · 2017-10-13T13:04:42Z

+Summary
+-------
+
+Core function


s/function/functions/ ?
Also ArgumentParser is a class, not a function.

Maybe «Core functionality» was meant.

ezio-melotti · 2017-10-13T13:07:19Z

+
+ ":class:`argparse.ArgumentParser`", "`prog`_, `description`_, `formatter_class`_", "``parser = argparse.ArgumentParser(prog='PROG', description='DESC', formatter_class=argparse.RawDescriptionHelpFormatter)``"
+ ":func:`ArgumentParser.add_argument`", "`name or flags`_, `action`_, `default`_, `type`_, `required`_, `help`_", "``parser.add_argument('-v', '--verbose', action='store_true', help='Show various debugging information')``"
+


With a code block it is not possible to link to the individual args, but I'm not sure that's really necessary since there are already links in one of the following tables.

ezio-melotti · 2017-10-13T13:08:20Z

+====================== =============================================== =========================================================================================================================
+`action`_ What to do on arguments ``'store'``, ``'store_const'``, ``'store_true'``, ``'append'``, ``append_const``, ``count``, ``help``, ``version``
+`default`_ Default value of arguments
+`type`_ Treat arguments as type ``int``, ``float``, ``bool``, ``argparse.FileType('w')``, ``callable function``


"Automatically converts the argument to the given type"

ezio-melotti · 2017-10-13T13:09:29Z

+Name Description Keywords
+====================== ================================================== =======================================================================================================================
+`nargs`_ Associates number of arguments ``N`` (an integer), ``'?'``, ``'*'``, ``'+'``, ``argparse.REMAINDER``
+`const`_ The constant values of name or flags


This is also not particularly clear.

ezio-melotti · 2017-10-13T13:10:39Z

+====================== ================================================== =======================================================================================================================
+`nargs`_ Associates number of arguments ``N`` (an integer), ``'?'``, ``'*'``, ``'+'``, ``argparse.REMAINDER``
+`const`_ The constant values of name or flags
+`choices`_ Arguments should selected from this set or values ``['foo', 'bar']``, ``range(1, 10)``, Any object that support ``in`` operator


"A container that lists the possible values"
(container could link to the glossary entry if there is one)

bedevere-bot · 2017-10-13T13:11:41Z

A Python core developer has requested some changes be made to your pull request before we can consider merging it. If you could please address their requests along with any other requests in other reviews from core developers that would be appreciated.

Once you have made the requested changes, please leave a comment on this pull request containing the phrase I have made the requested changes; please review again. I will then notify any core developers who have left a review that you're ready for them to take another look at this pull request.

flavianh · 2019-07-27T06:36:25Z

@merwok @ezio-melotti What's the status on this?

merwok · 2019-07-29T02:33:17Z

Review comments haven’t been addressed

flavianh · 2019-07-29T11:56:23Z

@merwok I'm not sure they will ever be addressed, @louisom 's repository is now marked unknown. We could either close this PR, or if you think it still has value I could take over for @louisom

rhettinger · 2019-08-22T05:52:59Z

I think the current state of the patch is hopeless. If some one is inclined to take a more professional pass at this, I think they would be better off starting from scratch.

bpo-21150: Add summary of argparse
0af37a6

the-knights-who-say-ni added the CLA signed label Apr 20, 2017

louisom changed the title ~~bpoAdd summary of argparse~~bpo-21150: Add summary of argparseApr 20, 2017

rhettinger self-assigned this Apr 26, 2017

merwok reviewed Sep 27, 2017
View reviewed changes

ezio-melotti requested changes Oct 13, 2017
View reviewed changes

bedevere-bot added the awaiting changes label Oct 13, 2017

merwok mentioned this pull request Feb 24, 2019
bpo-21150: add quick link/summary table to the top of argparse documentation #12005
Merged

matrixise added the docs Documentation in the Doc dir label May 15, 2019

rhettinger closed this Aug 22, 2019

rhettinger mentioned this pull request Apr 10, 2022
Add quick links table to argparse docs #65349
Closed


		":class:`argparse.ArgumentParser`", "`prog`_, `description`_, `formatter_class`_", "``parser = argparse.ArgumentParser(prog='PROG', description='DESC', formatter_class=argparse.RawDescriptionHelpFormatter)``"
		":func:`ArgumentParser.add_argument`", "`name or flags`_, `action`_, `default`_, `type`_, `required`_, `help`_", "``parser.add_argument('-v', '--verbose', action='store_true', help='Show various debugging information')``"

Uh oh!

Uh oh!

Conversation

louisom commented Apr 20, 2017• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mention-bot commented Apr 20, 2017

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bedevere-bot commented Oct 13, 2017

Uh oh!

flavianh commented Jul 27, 2019

Uh oh!

merwok commented Jul 29, 2019

Uh oh!

flavianh commented Jul 29, 2019

Uh oh!

rhettinger commented Aug 22, 2019

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

9 participants

louisom commented Apr 20, 2017•
edited
Loading