Document parse_known_args.

1 files changed, 18 insertions, 0 deletions

diff --git a/doc/source/other-methods.rst b/doc/source/other-methods.rst
index 1003aa3..5934554 100644
--- a/doc/source/other-methods.rst
+++ b/doc/source/other-methods.rst
@@ -1,6 +1,24 @@
 Other methods

 =============

 

+Partial parsing

+---------------

+

+.. method:: parse_known_args([args], [namespace])

+

+Sometimes a script may only parse a few of the command line arguments, passing the remaining arguments on to another script or program.

+In these cases, the :meth:`parse_known_args` method can be useful.

+It works much like :meth:`parse_args` except that it does not produce an error when extra arguments are present.

+Instead, it returns a two item tuple containing the populated namespace and the list of remaining argument strings.

+::

+

+  >>> parser = argparse.ArgumentParser()

+  >>> parser.add_argument('--foo', action='store_true')

+  >>> parser.add_argument('bar')

+  >>> parser.parse_known_args(['--foo', '--badger', 'BAR', 'spam'])

+  (Namespace(bar='BAR', foo=True), ['--badger', 'spam'])

+

+

 Printing help

 -------------