[Python-checkins] cpython (3.3): Issue #19814: Clarify argparse's docs w.r.t prefix matching

[eli.bendersky]

http://hg.python.org/cpython/rev/c457bd1935f9
changeset:   87702:c457bd1935f9
branch:      3.3
parent:      87692:b231e0c3fd26
user:        Eli Bendersky <eliben at gmail.com>
date:        Mon Dec 02 05:49:54 2013 -0800
summary:
  Issue #19814: Clarify argparse's docs w.r.t prefix matching

files:
  Doc/library/argparse.rst |  14 +++++++++++---
  1 files changed, 11 insertions(+), 3 deletions(-)


diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst
--- a/Doc/library/argparse.rst
+++ b/Doc/library/argparse.rst
@@ -1371,12 +1371,14 @@
    >>> parser.parse_args(['--', '-f'])
    Namespace(foo='-f', one=None)
 
+.. _prefix-matching:
 
-Argument abbreviations
-^^^^^^^^^^^^^^^^^^^^^^
+Argument abbreviations (prefix matching)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The :meth:`~ArgumentParser.parse_args` method allows long options to be
-abbreviated if the abbreviation is unambiguous::
+abbreviated to a prefix, if the abbreviation is unambiguous (the prefix matches
+a unique option)::
 
    >>> parser = argparse.ArgumentParser(prog='PROG')
    >>> parser.add_argument('-bacon')
@@ -1852,6 +1854,12 @@
    >>> parser.parse_known_args(['--foo', '--badger', 'BAR', 'spam'])
    (Namespace(bar='BAR', foo=True), ['--badger', 'spam'])
 
+.. warning::
+   :ref:`Prefix matching <prefix-matching>` rules apply to
+   :meth:`parse_known_args`. The parser may consume an option even if it's just
+   a prefix of one of its known options, instead of leaving it in the remaining
+   arguments list.
+
 
 Customizing file parsing
 ^^^^^^^^^^^^^^^^^^^^^^^^

-- 
Repository URL: http://hg.python.org/cpython