Added documentation for ns_provider

Author: kmvanbrunt

cmd2/cmd2.py

@@ -192,15 +192,16 @@ def cmd_wrapper(cmd2_instance, statement: Union[Statement, str]):
 
 
 def with_argparser_and_unknown_args(argparser: argparse.ArgumentParser, *,
-                                    ns_provider: Optional[Callable[[None], argparse.Namespace]] = None,
+                                    ns_provider: Optional[Callable[..., argparse.Namespace]] = None,
                                     preserve_quotes: bool = False) -> \
         Callable[[argparse.Namespace, List], Optional[bool]]:
     """A decorator to alter a cmd2 method to populate its ``args`` argument by parsing arguments with the given
     instance of argparse.ArgumentParser, but also returning unknown args as a list.
 
     :param argparser: unique instance of ArgumentParser
-    :param ns_provider: an optional function that provides the Namespace for parse_known_args().
-                        this is useful if the Namespace needs to be prepopulated based on instance data.
+    :param ns_provider: An optional function that accepts a cmd2.Cmd object as an argument and returns an
+                        argparse.Namespace. This is useful if the Namespace needs to be prepopulated with
+                        state data that affects parsing.
     :param preserve_quotes: if True, then arguments passed to argparse maintain their quotes
     :return: function that gets passed argparse-parsed args in a Namespace and a list of unknown argument strings
              A member called __statement__ is added to the Namespace to provide command functions access to the
@@ -251,14 +252,15 @@ def cmd_wrapper(cmd2_instance, statement: Union[Statement, str]):
 
 
 def with_argparser(argparser: argparse.ArgumentParser, *,
-                   ns_provider: Optional[Callable[[None], argparse.Namespace]] = None,
+                   ns_provider: Optional[Callable[..., argparse.Namespace]] = None,
                    preserve_quotes: bool = False) -> Callable[[argparse.Namespace], Optional[bool]]:
     """A decorator to alter a cmd2 method to populate its ``args`` argument by parsing arguments
     with the given instance of argparse.ArgumentParser.
 
     :param argparser: unique instance of ArgumentParser
-    :param ns_provider: an optional function that provides the Namespace for parse_args().
-                        this is useful if the Namespace needs to be prepopulated based on instance data.
+    :param ns_provider: An optional function that accepts a cmd2.Cmd object as an argument and returns an
+                        argparse.Namespace. This is useful if the Namespace needs to be prepopulated with
+                        state data that affects parsing.
     :param preserve_quotes: if True, then arguments passed to argparse maintain their quotes
     :return: function that gets passed the argparse-parsed args in a Namespace
              A member called __statement__ is added to the Namespace to provide command functions access to the

docs/argument_processing.rst

@@ -247,7 +247,7 @@ argument list instead of a string::
             pass
 
 
-Using the argument parser decorator and also receiving a a list of unknown positional arguments
+Using the argument parser decorator and also receiving a list of unknown positional arguments
 ===============================================================================================
 If you want all unknown arguments to be passed to your command as a list of strings, then
 decorate the command method with the ``@with_argparser_and_unknown_args`` decorator.
@@ -275,6 +275,28 @@ Here's what it looks like::
 
         ...
 
+Using custom namespace with argument parser decorators
+===============================================================================================
+In some cases, it may be necessary to write custom ``argparse`` code that is dependent on state data of your
+application.  To support this ability while still allowing use of the decorators, both ``@with_argparser`` and
+``@with_argparser_and_unknown_args`` have an optional argument called ``ns_provider``.
+
+``ns_provider`` is a Callable that accepts a ``cmd2.Cmd`` object as an argument and returns an ``argparse.Namespace``::
+
+    Callable[[cmd2.Cmd], argparse.Namespace]
+
+For example::
+
+    def settings_ns_provider(self) -> argparse.Namespace:
+        """Populate an argparse Namespace with current settings"""
+        ns = argparse.Namespace()
+        ns.app_settings = self.settings
+        return ns
+
+To use this function with the argparse decorators, do the following::
+
+    @with_argparser(my_parser, ns_provider=settings_ns_provider)
+
 Sub-commands
 ============
 Sub-commands are supported for commands using either the ``@with_argparser`` or