cmd2 3.0.0b1__tar.gz → 3.0.0b2__tar.gz

{cmd2-3.0.0b1 → cmd2-3.0.0b2}/CHANGELOG.md

@@ -24,6 +24,7 @@ time reading the [rich documentation](https://rich.readthedocs.io/).
       `value` property
     - Removed redundant setting of a parser's `prog` value in the `with_argparser()` decorator, as
       this is now handled centrally in `Cmd._build_parser()`
+    - The `auto_load_commands` argument to `cmd2.Cmd.__init__` now defaults to `False`
 
 - Enhancements
     - Enhanced all print methods (`poutput()`, `perror()`, `ppaged()`, etc.) to natively render

{cmd2-3.0.0b1 → cmd2-3.0.0b2}/Makefile

@@ -34,7 +34,6 @@ typecheck: ## Perform type checking
 test: ## Test the code with pytest.
 	@echo "🚀 Testing code: Running pytest"
 	@uv run python -Xutf8 -m pytest --cov --cov-config=pyproject.toml --cov-report=xml tests
-	@uv run python -Xutf8 -m pytest --cov --cov-config=pyproject.toml --cov-report=xml tests_isolated
 
 .PHONY: docs-test
 docs-test: ## Test if documentation can be built without warnings or errors

{cmd2-3.0.0b1 → cmd2-3.0.0b2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cmd2
-Version: 3.0.0b1
+Version: 3.0.0b2
 Summary: cmd2 - quickly build feature-rich and user-friendly interactive command line applications in Python
 Author: cmd2 Contributors
 License-Expression: MIT

{cmd2-3.0.0b1 → cmd2-3.0.0b2}/cmd2/cmd2.py

@@ -323,7 +323,7 @@ class Cmd(cmd.Cmd):
         terminators: list[str] | None = None,
         shortcuts: dict[str, str] | None = None,
         command_sets: Iterable[CommandSet] | None = None,
-        auto_load_commands: bool = True,
+        auto_load_commands: bool = False,
         allow_clipboard: bool = True,
         suggest_similar_command: bool = False,
     ) -> None:

{cmd2-3.0.0b1 → cmd2-3.0.0b2}/cmd2.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cmd2
-Version: 3.0.0b1
+Version: 3.0.0b2
 Summary: cmd2 - quickly build feature-rich and user-friendly interactive command line applications in Python
 Author: cmd2 Contributors
 License-Expression: MIT

{cmd2-3.0.0b1 → cmd2-3.0.0b2}/cmd2.egg-info/SOURCES.txt

@@ -109,8 +109,8 @@ docs/overview/index.md
 docs/overview/installation.md
 docs/overview/integrating.md
 docs/overview/resources.md
-docs/plugins/external_test.md
 docs/plugins/index.md
+docs/plugins/plugin_template.md
 docs/stylesheets/cmd2.css
 docs/stylesheets/readthedocs.css
 examples/.cmd2rc
@@ -267,21 +267,6 @@ examples/transcripts/quit.txt
 examples/transcripts/transcript_regex.txt
 plugins/README.txt
 plugins/tasks.py
-plugins/ext_test/CHANGELOG.md
-plugins/ext_test/README.md
-plugins/ext_test/build-pyenvs.sh
-plugins/ext_test/noxfile.py
-plugins/ext_test/pyproject.toml
-plugins/ext_test/setup.py
-plugins/ext_test/tasks.py
-plugins/ext_test/cmd2_ext_test/__init__.py
-plugins/ext_test/cmd2_ext_test/cmd2_ext_test.py
-plugins/ext_test/cmd2_ext_test/py.typed
-plugins/ext_test/cmd2_ext_test/pylintrc
-plugins/ext_test/examples/example.py
-plugins/ext_test/tests/__init__.py
-plugins/ext_test/tests/pylintrc
-plugins/ext_test/tests/test_ext_test.py
 plugins/template/CHANGELOG.md
 plugins/template/LICENSE
 plugins/template/README.md
@@ -305,7 +290,10 @@ tests/script.txt
 tests/test_argparse.py
 tests/test_argparse_completer.py
 tests/test_argparse_custom.py
+tests/test_argparse_subcommands.py
+tests/test_categories.py
 tests/test_cmd2.py
+tests/test_commandset.py
 tests/test_completion.py
 tests/test_future_annotations.py
 tests/test_history.py
@@ -350,10 +338,4 @@ tests/transcripts/singleslash.txt
 tests/transcripts/slashes_escaped.txt
 tests/transcripts/slashslash.txt
 tests/transcripts/spaces.txt
-tests/transcripts/word_boundaries.txt
-tests_isolated/__init__.py
-tests_isolated/test_commandset/__init__.py
-tests_isolated/test_commandset/conftest.py
-tests_isolated/test_commandset/test_argparse_subcommands.py
-tests_isolated/test_commandset/test_categories.py
-tests_isolated/test_commandset/test_commandset.py
+tests/transcripts/word_boundaries.txt

{cmd2-3.0.0b1 → cmd2-3.0.0b2}/codecov.yml

@@ -14,4 +14,3 @@ component_management:
 ignore:
   - "examples" # ignore example code folder
   - "tests" # ignore unit test code folder
-  - "tests_isolated" # ignore integration test code folder

{cmd2-3.0.0b1 → cmd2-3.0.0b2}/docs/features/modular_commands.md

@@ -4,18 +4,20 @@
 
 Cmd2 also enables developers to modularize their command definitions into
 [CommandSet][cmd2.CommandSet] objects. CommandSets represent a logical grouping of commands within a
-`cmd2` application. By default, all `CommandSet` objects will be discovered and loaded automatically
-when the [cmd2.Cmd][] class is instantiated with this mixin. This also enables the developer to
-dynamically add/remove commands from the cmd2 application. This could be useful for loadable plugins
-that add additional capabilities. Additionally, it allows for object-oriented encapsulation and
-garbage collection of state that is specific to a CommandSet.
+`cmd2` application. By default, `CommandSet` objects need to be manually registered. However, it is
+possible for all `CommandSet` objects to be discovered and loaded automatically when the
+[cmd2.Cmd][] class is instantiated with this mixin by setting `auto_load_commands=True`. This also
+enables the developer to dynamically add/remove commands from the `cmd2` application. This could be
+useful for loadable plugins that add additional capabilities. Additionally, it allows for
+object-oriented encapsulation and garbage collection of state that is specific to a CommandSet.
 
 ### Features
 
 - Modular Command Sets - Commands can be broken into separate modules rather than in one god class
   holding all commands.
 - Automatic Command Discovery - In your application, merely defining and importing a CommandSet is
-  sufficient for `cmd2` to discover and load your command. No manual registration is necessary.
+  sufficient for `cmd2` to discover and load your command if you set `auto_load_commands=True`. No
+  manual registration is necessary.
 - Dynamically Loadable/Unloadable Commands - Command functions and CommandSets can both be loaded
   and unloaded dynamically during application execution. This can enable features such as
   dynamically loaded modules that add additional commands.
@@ -71,7 +73,7 @@ class ExampleApp(cmd2.Cmd):
     CommandSets are automatically loaded. Nothing needs to be done.
     """
     def __init__(self, *args, **kwargs):
-        super().__init__(*args, **kwargs)
+        super().__init__(*args, auto_load_commands=True, **kwargs)
 
     def do_something(self, arg):
         self.poutput('this is the something command')
@@ -106,7 +108,7 @@ class ExampleApp(cmd2.Cmd):
     """
     def __init__(self, *args, **kwargs):
         # gotta have this or neither the plugin or cmd2 will initialize
-        super().__init__(*args, **kwargs)
+        super().__init__(*args, auto_load_commands=True, **kwargs)
 
     def do_something(self, arg):
         self.last_result = 5
@@ -289,7 +291,7 @@ class LoadableVegetables(CommandSet):
 
 class ExampleApp(cmd2.Cmd):
     """
-    CommandSets are automatically loaded. Nothing needs to be done.
+    CommandSets are loaded dynamically at runtime via other commands.
     """
 
     def __init__(self, *args, **kwargs):

{cmd2-3.0.0b1 → cmd2-3.0.0b2}/docs/plugins/index.md

@@ -2,6 +2,6 @@
 
 <!--intro-start-->
 
-- [External Test Plugin](external_test.md)
+- [cmd2 Plugin Template](plugin_template.md)
 
 <!--intro-end-->

cmd2-3.0.0b2/docs/plugins/plugin_template.md

@@ -0,0 +1,7 @@
+# cmd2 Plugin Template
+
+## Overview
+
+The [cmd2 Plugin Template](https://github.com/python-cmd2/cmd2/tree/main/plugins/template) is a
+general example that shows you how you can develop a plugin for `cmd2`. Plugins are generally mixin
+classes that add some extra functionality to your class which inherits from [cmd2.Cmd][].

{cmd2-3.0.0b1 → cmd2-3.0.0b2}/docs/testing.md

@@ -6,9 +6,10 @@ This covers special considerations when writing unit or integration tests for a
 
 ## Testing Commands
 
-The [External Test Plugin](plugins/external_test.md) provides a mixin class with a function that
-allows external calls to application commands. The `cmd2_ext_test.ExternalTestMixin.app_cmd`
-function captures and returns stdout, stderr, and the command-specific result data.
+We encourage `cmd2` application developers to look at the
+[cmd2 tests](https://github.com/python-cmd2/cmd2/tree/main/tests) for examples of how to perform
+unit and integration testing of `cmd2` commands. There are various helpers that will do things like
+capture and return stdout, stderr, and command-specific result data.
 
 ## Mocking
 

{cmd2-3.0.0b1 → cmd2-3.0.0b2}/docs/upgrades.md

@@ -106,3 +106,11 @@ however it now inherits from `argparse.HelpFormatter`. If you want RawText behav
 The benefit is that your `cmd2` applications now have more aesthetically pleasing help which
 includes color to make it quicker and easier to visually parse help text. This works for all
 supported versions of Python.
+
+### Other Changes
+
+- The `auto_load_commands` argument to `cmd2.Cmd.__init__` now defaults to `False`
+- Replaced `Settable.get_value()` and `Settable.set_value()` methods with a more Pythonic `value`
+  property
+- Removed redundant setting of a parser's `prog` value in the `with_argparser()` decorator, as this
+  is now handled centrally in `Cmd._build_parser()`

{cmd2-3.0.0b1 → cmd2-3.0.0b2}/mkdocs.yml

@@ -195,7 +195,7 @@ nav:
       - examples/examples.md
   - Plugins:
       - plugins/index.md
-      - plugins/external_test.md
+      - plugins/plugin_template.md
   - Testing:
       - testing.md
   - API Reference:

{cmd2-3.0.0b1 → cmd2-3.0.0b2}/plugins/tasks.py

@@ -10,16 +10,12 @@ import pathlib
 
 import invoke
 
-from plugins.ext_test import (
-    tasks as ext_test_tasks,
-)
 from plugins.template import (
     tasks as template_tasks,
 )
 
 # create namespaces
 namespace = invoke.Collection(
-    ext_test=ext_test_tasks,
     template=template_tasks,
 )
 namespace_clean = invoke.Collection('clean')
@@ -35,7 +31,6 @@ TASK_ROOT = pathlib.Path(__file__).resolve().parent
 TASK_ROOT_STR = str(TASK_ROOT)
 
 
-@invoke.task(pre=[ext_test_tasks.pytest])
 @invoke.task()
 def pytest(_) -> None:
     """Run tests and code coverage using pytest."""
@@ -44,7 +39,7 @@ def pytest(_) -> None:
 namespace.add_task(pytest)
 
 
-@invoke.task(pre=[ext_test_tasks.pytest_clean])
+@invoke.task()
 def pytest_clean(_) -> None:
     """Remove pytest cache and code coverage files and directories."""
 
@@ -52,7 +47,7 @@ def pytest_clean(_) -> None:
 namespace_clean.add_task(pytest_clean, 'pytest')
 
 
-@invoke.task(pre=[ext_test_tasks.mypy])
+@invoke.task()
 def mypy(_) -> None:
     """Run mypy optional static type checker."""
 
@@ -60,7 +55,7 @@ def mypy(_) -> None:
 namespace.add_task(mypy)
 
 
-@invoke.task(pre=[ext_test_tasks.mypy_clean])
+@invoke.task()
 def mypy_clean(_) -> None:
     """Remove mypy cache directory."""
     # pylint: disable=unused-argument
@@ -78,7 +73,7 @@ BUILDDIR = 'build'
 DISTDIR = 'dist'
 
 
-@invoke.task(pre=[ext_test_tasks.build_clean])
+@invoke.task()
 def build_clean(_) -> None:
     """Remove the build directory."""
 
@@ -86,7 +81,7 @@ def build_clean(_) -> None:
 namespace_clean.add_task(build_clean, 'build')
 
 
-@invoke.task(pre=[ext_test_tasks.dist_clean])
+@invoke.task()
 def dist_clean(_) -> None:
     """Remove the dist directory."""
 
@@ -107,7 +102,7 @@ def clean_all(_) -> None:
 namespace_clean.add_task(clean_all, 'all')
 
 
-@invoke.task(pre=[clean_all], post=[ext_test_tasks.sdist])
+@invoke.task(pre=[clean_all])
 def sdist(_) -> None:
     """Create a source distribution."""
 
@@ -115,7 +110,7 @@ def sdist(_) -> None:
 namespace.add_task(sdist)
 
 
-@invoke.task(pre=[clean_all], post=[ext_test_tasks.wheel])
+@invoke.task(pre=[clean_all])
 def wheel(_) -> None:
     """Build a wheel distribution."""
 
@@ -124,7 +119,7 @@ namespace.add_task(wheel)
 
 
 # ruff linter
-@invoke.task(pre=[ext_test_tasks.lint])
+@invoke.task()
 def lint(context) -> None:
     with context.cd(TASK_ROOT_STR):
         context.run("ruff check")
@@ -134,7 +129,7 @@ namespace.add_task(lint)
 
 
 # ruff formatter
-@invoke.task(pre=[ext_test_tasks.format])
+@invoke.task()
 def format(context) -> None:  # noqa: A001
     """Run formatter."""
     with context.cd(TASK_ROOT_STR):

{cmd2-3.0.0b1 → cmd2-3.0.0b2}/pyproject.toml

@@ -66,7 +66,6 @@ docs = [
     "setuptools>=64",
     "setuptools_scm>=8",
 ]
-plugins = ["cmd2-ext-test"]
 quality = ["pre-commit>=2.20.0"]
 test = [
     "codecov>=2",
@@ -84,17 +83,16 @@ disallow_untyped_defs = true
 exclude = [
     "^.git/",
     "^.venv/",
-    "^build/",          # .build directory
-    "^docs/",           # docs directory
+    "^build/",        # .build directory
+    "^docs/",         # docs directory
     "^dist/",
-    "^examples/",       # examples directory
-    "^plugins/*",       # plugins directory
-    "^noxfile\\.py$",   # nox config file
-    "setup\\.py$",      # any files named setup.py
+    "^examples/",     # examples directory
+    "^plugins/*",     # plugins directory
+    "^noxfile\\.py$", # nox config file
+    "setup\\.py$",    # any files named setup.py
     "^site/",
-    "^tasks\\.py$",     # tasks.py invoke config file
-    "^tests/",          # tests directory
-    "^tests_isolated/", # tests_isolated directory
+    "^tasks\\.py$",   # tasks.py invoke config file
+    "^tests/",        # tests directory
 ]
 files = ['.']
 show_column_numbers = true
@@ -271,7 +269,7 @@ mccabe.max-complexity = 49
 "plugins/*.py" = ["INP001"] # Module is part of an implicit namespace
 
 # Ingore various rulesets in test and plugins directories
-"{plugins,tests,tests_isolated}/*.py" = [
+"{plugins,tests}/*.py" = [
     "ANN",  # Ignore all type annotation rules in test folders
     "ARG",  # Ignore all unused argument warnings in test folders
     "D",    # Ignore all pydocstyle rules in test folders
@@ -315,7 +313,4 @@ packages = ["cmd2"]
 [tool.setuptools_scm]
 
 [tool.uv]
-default-groups = ["build", "dev", "plugins"]
-
-[tool.uv.sources]
-cmd2-ext-test = { path = "plugins/ext_test", editable = true }
+default-groups = ["build", "dev"]

{cmd2-3.0.0b1 → cmd2-3.0.0b2}/tasks.py

@@ -52,28 +52,18 @@ namespace.add_collection(namespace_clean, 'clean')
 
 
 @invoke.task()
-def pytest(context: Context, junit: bool = False, pty: bool = True, base: bool = False, isolated: bool = False) -> None:
+def pytest(context: Context, junit: bool = False, pty: bool = True) -> None:
     """Run tests and code coverage using pytest."""
     with context.cd(TASK_ROOT_STR):
         command_str = 'pytest '
         command_str += ' --cov=cmd2 '
         command_str += ' --cov-append --cov-report=term --cov-report=html '
 
-        if not base and not isolated:
-            base = True
-            isolated = True
-
         if junit:
             command_str += ' --junitxml=junit/test-results.xml '
 
-        if base:
-            tests_cmd = command_str + ' tests'
-            context.run(tests_cmd, pty=pty)
-        if isolated:
-            for _root, dirnames, _ in os.walk(str(TASK_ROOT / 'tests_isolated')):
-                for dir_name in dirnames:
-                    if dir_name.startswith('test_'):
-                        context.run(command_str + ' tests_isolated/' + dir_name)
+        tests_cmd = command_str + ' tests'
+        context.run(tests_cmd, pty=pty)
 
 
 namespace.add_task(pytest)

{cmd2-3.0.0b1 → cmd2-3.0.0b2}/tests/conftest.py

@@ -5,6 +5,7 @@ import sys
 from collections.abc import Callable
 from contextlib import redirect_stderr
 from typing import (
+    TYPE_CHECKING,
     ParamSpec,
     TextIO,
     TypeVar,
@@ -164,3 +165,87 @@ def find_subcommand(action: argparse.ArgumentParser, subcmd_names: list[str]) ->
                     return find_subcommand(choice, subcmd_names)
             break
     raise ValueError(f"Could not find subcommand '{subcmd_names}'")
+
+
+if TYPE_CHECKING:
+    _Base = cmd2.Cmd
+else:
+    _Base = object
+
+
+class ExternalTestMixin(_Base):
+    """A cmd2 plugin (mixin class) that exposes an interface to execute application commands from python"""
+
+    def __init__(self, *args, **kwargs):
+        """Initializes the ExternalTestMixin.
+
+        This class is intended to be used in multiple inheritance alongside `cmd2.Cmd` for an application class.
+        When doing this multiple inheritance, it is imperative that this mixin class come first.
+
+        :type self: cmd2.Cmd
+        :param args: arguments to pass to the superclass
+        :param kwargs: keyword arguments to pass to the superclass
+        """
+        # code placed here runs before cmd2 initializes
+        super().__init__(*args, **kwargs)
+        if not isinstance(self, cmd2.Cmd):
+            raise TypeError('The ExternalTestMixin class is intended to be used in multiple inheritance with cmd2.Cmd')
+        # code placed here runs after cmd2 initializes
+        self._pybridge = cmd2.py_bridge.PyBridge(self)
+
+    def app_cmd(self, command: str, echo: bool | None = None) -> cmd2.CommandResult:
+        """
+        Run the application command
+
+        :param command: The application command as it would be written on the cmd2 application prompt
+        :param echo: Flag whether the command's output should be echoed to stdout/stderr
+        :return: A CommandResult object that captures stdout, stderr, and the command's result object
+        """
+        try:
+            self._in_py = True
+            return self._pybridge(command, echo=echo)
+
+        finally:
+            self._in_py = False
+
+    def fixture_setup(self):
+        """Replicates the behavior of `cmdloop()` to prepare the application state for testing.
+
+        This method runs all preloop hooks and the preloop method to ensure the
+        application is in the correct state before running a test.
+
+        :type self: cmd2.Cmd
+        """
+
+        for func in self._preloop_hooks:
+            func()
+        self.preloop()
+
+    def fixture_teardown(self):
+        """Replicates the behavior of `cmdloop()` to tear down the application after a test.
+
+        This method runs all postloop hooks and the postloop method to clean up
+        the application state and ensure test isolation.
+
+        :type self: cmd2.Cmd
+        """
+        for func in self._postloop_hooks:
+            func()
+        self.postloop()
+
+
+class WithCommandSets(ExternalTestMixin, cmd2.Cmd):
+    """Class for testing custom help_* methods which override docstring help."""
+
+    def __init__(self, *args, **kwargs) -> None:
+        super().__init__(*args, **kwargs)
+
+
+@pytest.fixture
+def autoload_command_sets_app():
+    return WithCommandSets(auto_load_commands=True)
+
+
+@pytest.fixture
+def manual_command_sets_app():
+    return WithCommandSets(auto_load_commands=False)