From http://bugs.python.org/issue14191#msg155202:

ArgumentParser.parse_args(args=None, namespace=None)
...
However, nowhere is the args= parameter explained.  One example is given at the end of 15.4.4.6 showing the use of args= which apparently accepts a list of parameters, similar to the positional list of parameters that are used in all the other examples.  It might be nice to clarify that.

The 'args=' parameter is the same as the first positional parameter used in most of the examples.  That is normal Python behavior.

15.4.4.5. Beyond sys.argv
explains this alternative way of specifying argv.

Still 2 bullet points could be added to 15.4.4.

- args - A list of strings, default is sys.argv[1:] (link to 15.4.4.5.)
- namespace - A Namespace object, default is a new Namespace (link to 15.4.4.6.)

Maybe a 15.4.4.5. example using args=['1', '2', '3', '4'] would also be helpful.

This patch to argparse.rst adds the argument points to parse_args().  

It also adds two points to the 'Upgrading optparse code' section, one about using 'nargs=argparse.REMAINDER', and other about 'parse_known_args()'.

I'm not entirely happy with the format of the internal hyperlinks.

I changed the reference to the optparse allow_interspersed_args attribute to the disable_interspersed_args() method.

These docs changes seem reasonable, from a side-by-side view (I didn't attempt to look at the formatted results of applying the patch), to better document the current behavior.

I've turned this into a PR.  The example was already changed in a previous checkin.  I reworded the optparse porting addition to match the existing style of the list.

Thanks, David. I merged the backport PRs. Closing this.