Merge pull request #985 from python-cmd2/dynamic_value

Added Cmd2AttributeWrapper class

Author: kmvanbrunt

CHANGELOG.md

@@ -1,3 +1,11 @@
+## 1.3.6 (August 26, 2020)
+* Breaking changes
+    * The functions cmd2 adds to Namespaces (`get_statement()` and `get_handler()`) are now 
+    `Cmd2AttributeWrapper` objects named `cmd2_statement` and `cmd2_handler`. This makes it
+    easy to filter out which attributes in an `argparse.Namespace` were added by `cmd2`.
+* Deprecations
+    * ``Namespace.__statement__`` will be removed in `cmd2` 2.0.0. Use `Namespace.get_statement()` going forward.
+
 ## 1.3.5 (August 25, 2020)
 * Bug Fixes
     * Fixed `RecursionError` when printing an `argparse.Namespace` caused by custom attribute cmd2 was adding

cmd2/__init__.py

@@ -16,7 +16,7 @@
     pass
 
 from .ansi import style, fg, bg
-from .argparse_custom import Cmd2ArgumentParser, CompletionItem, set_default_argument_parser
+from .argparse_custom import Cmd2ArgumentParser, Cmd2AttributeWrapper, CompletionItem, set_default_argument_parser
 
 # Check if user has defined a module that sets a custom value for argparse_custom.DEFAULT_ARGUMENT_PARSER
 import argparse

cmd2/argparse_custom.py

@@ -221,7 +221,7 @@ def my_completer_method(self, text, line, begidx, endidx, arg_tokens)
 import sys
 # noinspection PyUnresolvedReferences,PyProtectedMember
 from argparse import ONE_OR_MORE, ZERO_OR_MORE, ArgumentError, _
-from typing import Callable, Optional, Tuple, Type, Union
+from typing import Any, Callable, Optional, Tuple, Type, Union
 
 from . import ansi, constants
 
@@ -904,6 +904,24 @@ def _print_message(self, message, file=None):
             ansi.style_aware_write(file, message)
 
 
+class Cmd2AttributeWrapper:
+    """
+    Wraps a cmd2-specific attribute added to an argparse Namespace.
+    This makes it easy to know which attributes in a Namespace are
+    arguments from a parser and which were added by cmd2.
+    """
+    def __init__(self, attribute: Any):
+        self.__attribute = attribute
+
+    def get(self) -> Any:
+        """Get the value of the attribute"""
+        return self.__attribute
+
+    def set(self, new_val: Any) -> None:
+        """Set the value of the attribute"""
+        self.__attribute = new_val
+
+
 # The default ArgumentParser class for a cmd2 app
 DEFAULT_ARGUMENT_PARSER = Cmd2ArgumentParser
 

cmd2/cmd2.py

@@ -2685,7 +2685,7 @@ def _cmdloop(self) -> None:
     def do_alias(self, args: argparse.Namespace) -> None:
         """Manage aliases"""
         # Call handler for whatever subcommand was selected
-        handler = args.get_handler()
+        handler = args.cmd2_handler.get()
         handler(args)
 
     # alias -> create
@@ -2812,7 +2812,7 @@ def _alias_list(self, args: argparse.Namespace) -> None:
     def do_macro(self, args: argparse.Namespace) -> None:
         """Manage macros"""
         # Call handler for whatever subcommand was selected
-        handler = args.get_handler()
+        handler = args.cmd2_handler.get()
         handler(args)
 
     # macro -> create

cmd2/decorators.py

@@ -4,6 +4,7 @@
 from typing import TYPE_CHECKING, Any, Callable, Dict, Iterable, List, Optional, Tuple, Union
 
 from . import constants
+from .argparse_custom import Cmd2AttributeWrapper
 from .exceptions import Cmd2ArgparseError
 from .parsing import Statement
 
@@ -186,10 +187,10 @@ def with_argparser_and_unknown_args(parser: argparse.ArgumentParser, *,
                         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 :class:`cmd2.Statement`
-             object. This can be useful if the command function needs to know the command line.
-             ``__statement__`` can also be retrieved by calling ``get_statement()`` on the ``Namespace``.
+             of unknown argument strings. A :class:`cmd2.argparse_custom.Cmd2AttributeWrapper` called
+             ``cmd2_statement`` is included in the ``Namespace`` to provide access to the :class:`cmd2.Statement`
+             object. that was created when parsing the command line. This can be useful if the command function
+             needs to know the command line.
 
     :Example:
 
@@ -223,12 +224,12 @@ def with_argparser(parser: argparse.ArgumentParser, *,
     :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
+    :param preserve_quotes: if ``True``, then arguments passed to argparse maintain their quotes
     :param with_unknown_args: if true, then capture unknown args
-    :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
-             Statement object. This can be useful if the command function needs to know the command line.
-             ``__statement__`` can also be retrieved by calling ``get_statement()`` on the ``Namespace``.
+    :return: function that gets passed argparse-parsed args in a ``Namespace``
+             A :class:`cmd2.argparse_custom.Cmd2AttributeWrapper` called ``cmd2_statement`` is included
+             in the ``Namespace`` to provide access to the :class:`cmd2.Statement` object that was created when
+             parsing the command line. This can be useful if the command function needs to know the command line.
 
     :Example:
 
@@ -298,13 +299,20 @@ def cmd_wrapper(*args: Any, **kwargs: Dict[str, Any]) -> Optional[bool]:
             except SystemExit:
                 raise Cmd2ArgparseError
             else:
-                # Add statement to Namespace and a getter function for it
+                # Add statement to Namespace as __statement__ (this is deprecated and will be removed in 2.0)
                 setattr(ns, constants.NS_ATTR_STATEMENT, statement)
-                setattr(ns, 'get_statement', lambda: statement)
 
-                # Add getter function for subcmd handler, which can be None
-                subcmd_handler = getattr(ns, constants.NS_ATTR_SUBCMD_HANDLER, None)
-                setattr(ns, 'get_handler', lambda: subcmd_handler)
+                # Add wrapped statement to Namespace as cmd2_statement
+                setattr(ns, 'cmd2_statement', Cmd2AttributeWrapper(statement))
+
+                # Add wrapped subcmd handler (which can be None) to Namespace as cmd2_handler
+                handler = getattr(ns, constants.NS_ATTR_SUBCMD_HANDLER, None)
+                setattr(ns, 'cmd2_handler', Cmd2AttributeWrapper(handler))
+
+                # Remove the subcmd handler attribute from the Namespace
+                # since cmd2_handler is how a developer accesses it.
+                if hasattr(ns, constants.NS_ATTR_SUBCMD_HANDLER):
+                    delattr(ns, constants.NS_ATTR_SUBCMD_HANDLER)
 
                 args_list = _arg_swap(args, statement, *new_args)
                 return func(*args_list, **kwargs)

docs/features/argument_processing.rst

@@ -13,9 +13,8 @@ handles the following for you:
 
 3. Passes the resulting ``argparse.Namespace`` object to your command function.
    The ``Namespace`` includes the ``Statement`` object that was created when
-   parsing the command line. It is stored in the ``__statement__`` attribute of
-   the ``Namespace`` and can also be retrieved by calling ``get_statement()``
-   on the ``Namespace``.
+   parsing the command line. It can be retrieved by calling
+   ``cmd2_statement.get()`` on the ``Namespace``.
 
 4. Adds the usage message from the argument parser to your command.
 
@@ -391,10 +390,13 @@ Reserved Argument Names
 Namespaces. To avoid naming collisions, do not use any of the names for your
 argparse arguments.
 
+- ``cmd2_statement`` - ``cmd2.Cmd2AttributeWrapper`` object containing
+  ``cmd2.Statement`` object that was created when parsing the command line.
 - ``__statement__`` - ``cmd2.Statement`` object that was created when parsing
-  the command line.
-- ``get_statement()`` - convenience function which returns the ``Statement``
-- ``__subcmd_handler__`` - points to subcommand handler function. This is added
-  when using the ``@cmd2.as_subcommand_to`` decorator.
-- ``get_handler()`` - convenience function which returns the subcommand handler
-  or ``None`` if one was not set
+  the command line. (This is deprecated and will be removed in 2.0.0.) Use
+  ``cmd2_statement`` instead.
+
+- ``__subcmd_handler__`` - used by cmd2 to identify the handler for a
+  subcommand created with ``@cmd2.as_subcommand_to`` decorator.
+- ``cmd2_handler`` - ``cmd2.Cmd2AttributeWrapper`` object containing
+  a subcommand handler function or ``None`` if one was not set.

docs/features/modular_commands.rst

@@ -316,7 +316,7 @@ command and each CommandSet
 
         @with_argparser(cut_parser)
         def do_cut(self, ns: argparse.Namespace):
-            handler = ns.get_handler()
+            handler = ns.cmd2_handler.get()
             if handler is not None:
                 # Call whatever subcommand function was selected
                 handler(ns)

docs/testing.rst

@@ -38,7 +38,7 @@ this, you should always mock with `Autospeccing <python_mock_autospeccing_>`_ or
 enabled.
 
 Example of spec=True
-====================
+~~~~~~~~~~~~~~~~~~~~
 .. code-block:: python
 
     def test_mocked_methods():

examples/decorator_example.py

@@ -67,7 +67,7 @@ def do_speak(self, args: argparse.Namespace):
     def do_tag(self, args: argparse.Namespace):
         """create an html tag"""
         # The Namespace always includes the Statement object created when parsing the command line
-        statement = args.get_statement()
+        statement = args.cmd2_statement.get()
 
         self.poutput("The command line you ran was: {}".format(statement.command_and_args))
         self.poutput("It generated this tag:")

examples/modular_subcommands.py

@@ -98,7 +98,7 @@ def do_unload(self, ns: argparse.Namespace):
     @with_argparser(cut_parser)
     def do_cut(self, ns: argparse.Namespace):
         # Call handler for whatever subcommand was selected
-        handler = ns.get_handler()
+        handler = ns.cmd2_handler.get()
         if handler is not None:
             handler(ns)
         else: