The current argparse documentation is not easy to read people new to python.

http://docs.python.org/dev/library/argparse.html#choices

{{{
current: parser.add_argument('foo', choices='abc')
}}}

Please make this more explicit:
{{{
better: parser.add_argument('foo', choices=['one', 'two', 'three'])
}}}

{{{
current: parser.parse_args('c'.split()) # looks like perl to me
}}}

{{{
better: parser.parse_args(['c'])
}}}

Next: Please use a more common type, not "complex" in the choices example. It confuses a lot of people.

+1

+1.  By the way, I included a couple fixes similar to these in a patch posted to issue 16878.

Patch attached.

The new examples are much better and to me the patch looks ready to apply.

New changeset b2bb3219d36d by Chris Jerdonek in branch '2.7':
Issue #16933: Improve choices examples in argparse documentation.
http://hg.python.org/cpython/rev/b2bb3219d36d

New changeset eaa2a6074741 by Chris Jerdonek in branch '3.2':
Issue #16933 (2.7 forward-port): Improve choices examples in argparse docs.
http://hg.python.org/cpython/rev/eaa2a6074741

New changeset de9eb3031f5a by Chris Jerdonek in branch '3.3':
Issue #16933 (merge from 3.2): Improve choices examples in argparse docs.
http://hg.python.org/cpython/rev/de9eb3031f5a

New changeset bddbaaf332d7 by Chris Jerdonek in branch 'default':
Issue #16933 (merge from 3.3): Improve choices examples in argparse docs.
http://hg.python.org/cpython/rev/bddbaaf332d7

Thanks for reporting the suggestion, Thomas.  And thanks for looking over the patch, Terry.

There still is one "choices='XYZ'" example (16.4.5.1. Sub-commands) but the focus isn't on choices.