add "Name Collision" section to argparse docs

[bethard]

BPO	15428

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2012-07-23.00:00:31.958>
labels = ['type-feature', 'docs']
title = 'add "Name Collision" section to argparse docs'
updated_at = <Date 2014-08-07.23:27:58.493>
user = 'https://bugs.python.org/bethard'

bugs.python.org fields:

activity = <Date 2014-08-07.23:27:58.493>
actor = 'paul.j3'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2012-07-23.00:00:31.958>
creator = 'bethard'
dependencies = []
files = []
hgrepos = []
issue_num = 15428
keywords = []
message_count = 2.0
messages = ['166185', '225046']
nosy_count = 3.0
nosy_names = ['bethard', 'docs@python', 'paul.j3']
pr_nums = []
priority = 'normal'
resolution = None
stage = None
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue15428'
versions = ['Python 2.7', 'Python 3.4', 'Python 3.5']

Linked PRs

• GH-59633: Clarify dest collisions in argparse docs #150987
• [3.15] GH-59633: Clarify dest collisions in argparse docs (GH-150987) #151188
• [3.14] GH-59633: Clarify dest collisions in argparse docs (GH-150987) #151194
• [3.13] GH-59633: Clarify dest collisions in argparse docs (GH-150987) #151196

[bethard]

Several bugs (e.g. bpo-15327 and bpo-15271) have been filed suggesting that people aren't really clear on how argparse handles argument name collisions or how they can get it to do what they want.

I think these problems could probably be solved by a "Name Collision" section (or something like that) in the argparse documentation. It would give a few example problems and show how to resolve them. Some things to include:

• What happens when two arguments have the same dest (bpo-15271), with solutions including action='append' or different dest= values combined with identical metavar= values.

• What happens when a parser and a sub-parser share some of the same argument names (bpo-15327), with solutions including specifying different dest= values for the parser and sub-parser

• A brief mention and cross-reference to the "conflict_handler" section.

[paulj3]

On Stackoverflow a couple of posters have asked about nesting namespaces as a way of separating the parser and subparser arguments.

http://stackoverflow.com/questions/15782948
http://stackoverflow.com/questions/18668227

One solution that I rather like http://stackoverflow.com/a/18709860/901925

uses a custom Namespace class that recognizes a 'dest' like

 p.add_argument('--deep', dest='test.doo.deep')

and produces

 Nestedspace(foo='test', test=Nestedspace(bar='baz', doo=Nestedspace(deep='doodod')))

I wonder if a simplified version of this could be added to the Namespace section in the documentation.

There are 2 sides to the name conflict issue:

• what control does the programmer have over names (esp. when using [parents] and subparsers)?

• how does the programmer want to access the arguments in the resulting namespace?