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

Doc/library/argparse.rst

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


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

Doc/library/argparse.rst

+
+    ":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

Doc/library/argparse.rst

+.. _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

Doc/library/argparse.rst

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

Doc/library/argparse.rst

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

Doc/library/argparse.rst

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

Doc/library/argparse.rst

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

Doc/library/argparse.rst

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

Doc/library/argparse.rst

+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

Doc/library/argparse.rst

+
+    ":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

Doc/library/argparse.rst

+====================== =============================================== =========================================================================================================================
+`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

Doc/library/argparse.rst

+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

Doc/library/argparse.rst

+====================== ================================================== =======================================================================================================================
+`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 argparse Apr 20, 2017

rhettinger self-assigned this Apr 26, 2017

merwok reviewed Sep 27, 2017

View reviewed changes

Doc/library/argparse.rst

^^^^^^^^^^^^^

.. csv-table::

:header: "Name", "Common Used Arguments", "Example"

Copy link

Member

merwok Sep 27, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Commonly*

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!

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