Added documentation stating that parsers passed to argparse decorators need to be unique

Also:
- Modified table_display.py to demonstrate a workaround

1 files changed, 14 insertions, 2 deletions

diff --git a/docs/argument_processing.rst b/docs/argument_processing.rst
index 8aed7498..9d13a7c8 100644
--- a/docs/argument_processing.rst
+++ b/docs/argument_processing.rst
@@ -25,10 +25,10 @@ Using the argument parser decorator
 ===================================
 
 For each command in the ``cmd2`` subclass which requires argument parsing,
-create an instance of ``argparse.ArgumentParser()`` which can parse the
+create a unique instance of ``argparse.ArgumentParser()`` which can parse the
 input appropriately for the command. Then decorate the command method with
 the ``@with_argparser`` decorator, passing the argument parser as the
-first parameter to the decorator. This changes the second argumen to the command method, which will contain the results
+first parameter to the decorator. This changes the second argument to the command method, which will contain the results
 of ``ArgumentParser.parse_args()``.
 
 Here's what it looks like::
@@ -54,6 +54,16 @@ Here's what it looks like::
          for i in range(min(repetitions, self.maxrepeats)):
             self.poutput(arg)
 
+.. warning::
+
+    It is important that each command which uses the ``@with_argparser`` decorator be passed a unique instance of a
+    parser.  This limitation is due to bugs in CPython prior to Python 3.7 which make it impossible to make a deep copy
+    of an instance of a ``argparse.ArgumentParser``.
+
+    See the table_display_ example for a work-around that demonstrates how to create a function which returns a unique
+    instance of the parser you want.
+
+
 .. note::
 
    The ``@with_argparser`` decorator sets the ``prog`` variable in
@@ -61,6 +71,8 @@ Here's what it looks like::
    This will override anything you specify in ``prog`` variable when
    creating the argument parser.
 
+.. _table_display: https://github.com/python-cmd2/cmd2/blob/master/examples/table_display.py
+
 
 Help Messages
 =============