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 bpo-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 bpo-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 bpo-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 bpo-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 bpo-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.