cmd2 3.0.0b1__tar.gz → 3.0.0rc1__tar.gz

{cmd2-3.0.0b1 → cmd2-3.0.0rc1}/.pre-commit-config.yaml

@@ -9,12 +9,12 @@ repos:
       - id: trailing-whitespace
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: "v0.13.0"
+    rev: "v0.13.2"
     hooks:
       - id: ruff-format
-        args: [--config=pyproject.toml]
+        args: [--config=ruff.toml]
       - id: ruff-check
-        args: [--config=pyproject.toml, --fix, --exit-non-zero-on-fix]
+        args: [--config=ruff.toml, --fix, --exit-non-zero-on-fix]
 
   - repo: https://github.com/pre-commit/mirrors-prettier
     rev: "v3.1.0"

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

@@ -1,4 +1,4 @@
-## 3.0.0 (TBD, 2025)
+## 3.0.0 (October TBD, 2025)
 
 ### Summary
 
@@ -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
@@ -51,6 +52,12 @@ time reading the [rich documentation](https://rich.readthedocs.io/).
     - Fixed a redirection bug where `cmd2` could unintentionally overwrite an application's
       `sys.stdout`
 
+- Migration Aids - these will help you iteratively migrate to `cmd2` 3.x in stages
+    - Published new [cmd2-ansi](https://pypi.org/project/cmd2-ansi/) module which is a backport of
+      the `cmd2.ansi` module present in `cmd2` 2.7.0
+    - Published new [cmd2-table](https://pypi.org/project/cmd2-table/) module which is a backport of
+      the `cmd2.table_creator` module present in `cmd2` 2.7.0
+
 ## 2.7.0 (June 30, 2025)
 
 - Enhancements

{cmd2-3.0.0b1 → cmd2-3.0.0rc1}/MANIFEST.in

@@ -1,4 +1,4 @@
-include LICENSE README.md CHANGELOG.md mkdocs.yml pyproject.toml tasks.py
+include LICENSE README.md CHANGELOG.md mkdocs.yml pyproject.toml ruff.toml tasks.py
 recursive-include examples *
 recursive-include tests *
 recursive-include docs *

{cmd2-3.0.0b1 → cmd2-3.0.0rc1}/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.0rc1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cmd2
-Version: 3.0.0b1
+Version: 3.0.0rc1
 Summary: cmd2 - quickly build feature-rich and user-friendly interactive command line applications in Python
 Author: cmd2 Contributors
 License-Expression: MIT
@@ -58,7 +58,8 @@ when using cmd.
 
 > :warning: **cmd2 is now "feature complete" for the `2.x` branch and is actively working on the
 > 3.0.0 release on the `main` branch. New features will only be addressed in 3.x moving forwards. If
-> need be, we will still fix bugs in 2.x.**
+> need be, we will still fix bugs in 2.x. A beta version, 3.0.0b2, is available for testing and we
+> would appreciate feedback.**
 
 ## The developers toolbox
 

{cmd2-3.0.0b1 → cmd2-3.0.0rc1}/README.md

@@ -27,7 +27,8 @@ when using cmd.
 
 > :warning: **cmd2 is now "feature complete" for the `2.x` branch and is actively working on the
 > 3.0.0 release on the `main` branch. New features will only be addressed in 3.x moving forwards. If
-> need be, we will still fix bugs in 2.x.**
+> need be, we will still fix bugs in 2.x. A beta version, 3.0.0b2, is available for testing and we
+> would appreciate feedback.**
 
 ## The developers toolbox
 

{cmd2-3.0.0b1 → cmd2-3.0.0rc1}/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.0rc1}/cmd2/plugin.py

@@ -1,4 +1,4 @@
-"""Classes for the cmd2 plugin system."""
+"""Classes for the cmd2 lifecycle hooks that you can register multiple callback functions/methods with."""
 
 from dataclasses import (
     dataclass,

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cmd2
-Version: 3.0.0b1
+Version: 3.0.0rc1
 Summary: cmd2 - quickly build feature-rich and user-friendly interactive command line applications in Python
 Author: cmd2 Contributors
 License-Expression: MIT
@@ -58,7 +58,8 @@ when using cmd.
 
 > :warning: **cmd2 is now "feature complete" for the `2.x` branch and is actively working on the
 > 3.0.0 release on the `main` branch. New features will only be addressed in 3.x moving forwards. If
-> need be, we will still fix bugs in 2.x.**
+> need be, we will still fix bugs in 2.x. A beta version, 3.0.0b2, is available for testing and we
+> would appreciate feedback.**
 
 ## The developers toolbox
 

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

@@ -12,6 +12,7 @@ codecov.yml
 mkdocs.yml
 package.json
 pyproject.toml
+ruff.toml
 tasks.py
 cmd2/__init__.py
 cmd2/argparse_completer.py
@@ -103,14 +104,14 @@ docs/migrating/index.md
 docs/migrating/minimum.md
 docs/migrating/next_steps.md
 docs/migrating/why.md
+docs/mixins/index.md
+docs/mixins/mixin_template.md
 docs/overrides/main.html
 docs/overview/alternatives.md
 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/stylesheets/cmd2.css
 docs/stylesheets/readthedocs.css
 examples/.cmd2rc
@@ -124,6 +125,7 @@ examples/cmd_as_argument.py
 examples/color.py
 examples/command_sets.py
 examples/custom_parser.py
+examples/custom_types.py
 examples/default_categories.py
 examples/dynamic_commands.py
 examples/environment.py
@@ -134,6 +136,7 @@ examples/hello_cmd2.py
 examples/help_categories.py
 examples/hooks.py
 examples/migrating.py
+examples/mixin.py
 examples/modular_commands.py
 examples/paged_output.py
 examples/persistent_history.py
@@ -265,37 +268,6 @@ examples/transcripts/exampleSession.txt
 examples/transcripts/pirate.transcript
 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
-plugins/template/build-pyenvs.sh
-plugins/template/noxfile.py
-plugins/template/setup.py
-plugins/template/tasks.py
-plugins/template/cmd2_myplugin/__init__.py
-plugins/template/cmd2_myplugin/myplugin.py
-plugins/template/cmd2_myplugin/pylintrc
-plugins/template/examples/example.py
-plugins/template/tests/__init__.py
-plugins/template/tests/pylintrc
-plugins/template/tests/test_myplugin.py
 tests/.cmd2rc
 tests/__init__.py
 tests/conftest.py
@@ -305,7 +277,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 +325,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.0rc1}/codecov.yml

@@ -5,13 +5,8 @@ component_management:
       name: cmd2 # this is a display name, and can be changed freely
       paths:
         - cmd2/**
-    - component_id: plugins
-      name: plugins
-      paths:
-        - plugins/**
 
 # Ignore certain paths, all files under these paths will be skipped during processing
 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.0rc1}/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.0rc1}/docs/index.md

@@ -53,10 +53,10 @@ app.cmdloop()
     end="<!--intro-end-->"
 %}
 
-## Plugins
+## Mixins
 
 {%
-   include-markdown "./plugins/index.md"
+   include-markdown "./mixins/index.md"
     start="<!--intro-start-->"
     end="<!--intro-end-->"
 %}

cmd2-3.0.0rc1/docs/mixins/index.md

@@ -0,0 +1,7 @@
+# Mixins
+
+<!--intro-start-->
+
+- [cmd2 Mixin Template](mixin_template.md)
+
+<!--intro-end-->

cmd2-3.0.0rc1/docs/mixins/mixin_template.md

@@ -0,0 +1,170 @@
+# cmd2 Mixin Template
+
+## Mixin Classes in General
+
+In Python, a mixin is a class designed to provide a specific set of functionalities to other classes
+through multiple inheritance. Mixins are not intended to be instantiated on their own; rather, they
+serve as a way to "mix in" or compose behaviors into a base class without creating a rigid "is-a"
+relationship.
+
+For more information about Mixin Classes, we recommend this `Real Python` article on
+[What Are Mixin Classes in Python?](https://realpython.com/python-mixin/).
+
+## Overview of cmd2 mixins
+
+If you have some set of re-usable behaviors that you wish to apply to multiple different `cmd2`
+applications, then creating a mixin class to encapsulate this behavior can be a great idea. It is
+one way to extend `cmd2` by relying on multiple inheritance. It is quick and easy, but there are
+some potential pitfalls you should be aware of so you know how to do it correctly.
+
+The [mixins.py](https://github.com/python-cmd2/cmd2/blob/main/examples/mixins.py) example is a
+general example that shows you how you can develop a mixin class for `cmd2` applicaitons. In the
+past we have referred to these as "Plugins", but in retrospect that probably isn't the best name for
+them. They are generally mixin classes that add some extra functionality to your class which
+inherits from [cmd2.Cmd][].
+
+## Using this template
+
+This file provides a very basic template for how you can create your own cmd2 Mixin class to
+encapsulate re-usable behavior that can be applied to multiple `cmd2` applications via multiple
+inheritance.
+
+## Naming
+
+If you decide to publish your Mixin as a Python package, you should consider prefixing the name of
+your project with `cmd2-`. If you take this approach, then within that project, you should have a
+package with a prefix of `cmd2_`.
+
+## Adding functionality
+
+There are many ways to add functionality to `cmd2` using a mixin. A mixin is a class that
+encapsulates and injects code into another class. Developers who use a mixin in their `cmd2`
+project, will inject the mixin's code into their subclass of [cmd2.Cmd][].
+
+### Mixin and Initialization
+
+The following short example shows how to create a mixin class and how everything gets initialized.
+
+Here's the mixin:
+
+```python
+class MyMixin:
+    def __init__(self, *args, **kwargs):
+        # code placed here runs before cmd2.Cmd initializes
+        super().__init__(*args, **kwargs)
+        # code placed here runs after cmd2.Cmd initializes
+```
+
+and an example app which uses the mixin:
+
+```python
+import cmd2
+
+
+class Example(MyMixin, cmd2.Cmd):
+    """A cmd2 application class to show how to use a mixin class."""
+
+    def __init__(self, *args, **kwargs):
+        # code placed here runs before cmd2.Cmd or
+        # any mixins initialize
+        super().__init__(*args, **kwargs)
+        # code placed here runs after cmd2.Cmd and
+        # all mixins have initialized
+```
+
+Note how the mixin must be inherited (or mixed in) before `cmd2.Cmd`. This is required for two
+reasons:
+
+- The `cmd.Cmd.__init__()` method in the python standard library does not call `super().__init__()`.
+  Because of this oversight, if you don't inherit from `MyMixin` first, the `MyMixin.__init__()`
+  method will never be called.
+- You may want your mixin to be able to override methods from `cmd2.Cmd`. If you mixin the mixin
+  class after `cmd2.Cmd`, the python method resolution order will call `cmd2.Cmd` methods before it
+  calls those in your mixin.
+
+### Add commands
+
+Your mixin can add user visible commands. You do it the same way in a mixin that you would in a
+`cmd2.Cmd` app:
+
+```python
+class MyMixin:
+
+    def do_say(self, statement):
+        """Simple say command"""
+        self.poutput(statement)
+```
+
+You have all the same capabilities within the mixin that you do inside a `cmd2.Cmd` app, including
+argument parsing via decorators and custom help methods.
+
+### Add (or hide) settings
+
+A mixin may add user controllable settings to the application. Here's an example:
+
+```python
+class MyMixin:
+    def __init__(self, *args, **kwargs):
+        # code placed here runs before cmd2.Cmd initializes
+        super().__init__(*args, **kwargs)
+        # code placed here runs after cmd2.Cmd initializes
+        self.mysetting = 'somevalue'
+        self.settable.update({'mysetting': 'short help message for mysetting'})
+```
+
+You can also hide settings from the user by removing them from `self.settable`.
+
+### Decorators
+
+Your mixin can provide a decorator which users of your mixin can use to wrap functionality around
+their own commands.
+
+### Override methods
+
+Your mixin can override core `cmd2.Cmd` methods, changing their behavior. This approach should be
+used sparingly, because it is very brittle. If a developer chooses to use multiple mixins in their
+application, and several of the mixins override the same method, only the first mixin to be mixed in
+will have the overridden method called.
+
+Hooks are a much better approach.
+
+### Hooks
+
+Mixins can register hooks, which are called by `cmd2.Cmd` during various points in the application
+and command processing lifecycle. Mixins should not override any of the legacy `cmd` hook methods,
+instead they should register their hooks as
+[described](https://cmd2.readthedocs.io/en/latest/hooks.html) in the `cmd2` documentation.
+
+You should name your hooks so that they begin with the name of your mixin. Hook methods get mixed
+into the `cmd2` application and this naming convention helps avoid unintentional method overriding.
+
+Here's a simple example:
+
+```python
+class MyMixin:
+
+    def __init__(self, *args, **kwargs):
+        # code placed here runs before cmd2 initializes
+        super().__init__(*args, **kwargs)
+        # code placed here runs after cmd2 initializes
+        # this is where you register any hook functions
+        self.register_postparsing_hook(self.cmd2_mymixin_postparsing_hook)
+
+    def cmd2_mymixin_postparsing_hook(self, data: cmd2.plugin.PostparsingData) -> cmd2.plugin.PostparsingData:
+        """Method to be called after parsing user input, but before running the command"""
+        self.poutput('in postparsing_hook')
+        return data
+```
+
+Registration allows multiple mixins (or even the application itself) to each inject code to be
+called during the application or command processing lifecycle.
+
+See the [cmd2 hook documentation](https://cmd2.readthedocs.io/en/latest/hooks.html) for full details
+of the application and command lifecycle, including all available hooks and the ways hooks can
+influence the lifecycle.
+
+### Classes and Functions
+
+Your mixin can also provide classes and functions which can be used by developers of `cmd2` based
+applications. Describe these classes and functions in your documentation so users of your mixin will
+know what's available.

{cmd2-3.0.0b1 → cmd2-3.0.0rc1}/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.0rc1}/docs/upgrades.md

@@ -20,6 +20,18 @@ The functionality within the `cmd2.ansi` module has either been removed or chang
 `rich` and moved to one of the new modules: [cmd2.string_utils][], [cmd2.styles][], or
 [cmd2.terminal_utils][].
 
+To ease the migration path from `cmd2` 2.x to 3.x, we have created the `cmd2-ansi` module which is a
+backport of the `cmd2.ansi` module present in `cmd2` 2.7.0 in a standalone fashion. Relevant links:
+
+- PyPI: [cmd2-ansi](https://pypi.org/project/cmd2-ansi/)
+- GitHub: [cmd2-ansi](https://github.com/python-cmd2/cmd2-ansi)
+
+To use this backport:
+
+```Python
+from cmd2_ansi import ansi
+```
+
 #### table_creator
 
 The `cmd2.table_creator` module no longer exists. Please see rich's documentation on
@@ -31,6 +43,19 @@ demonstrates how to use `rich` tables in a `cmd2` application.
 offered. We apologize for this backwards incompatibility, but the APIs were fundamentally different
 and we could not figure out a way to create a backwards-compatibility wrapper.
 
+To ease the migration path from `cmd2` 2.x to 3.x, we have created the `cmd2-table` module which is
+a backport of the `cmd2.table_creator` module present in `cmd2` 2.7.0 in a standalone fashion.
+Relevant links:
+
+- PyPI: [cmd2-table](https://pypi.org/project/cmd2-table/)
+- GitHub: [cmd2-table](https://github.com/python-cmd2/cmd2-table)
+
+To use this backport:
+
+```Python
+from cmd2_table import table_creator
+```
+
 ### Added modules
 
 #### colors
@@ -106,3 +131,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.0rc1}/examples/README.md

@@ -32,6 +32,8 @@ each:
       subcommands, etc.
 - [custom_parser.py](https://github.com/python-cmd2/cmd2/blob/main/examples/custom_parser.py)
     - Demonstrates how to create your own custom `Cmd2ArgumentParser`
+- [custom_types.py](https://github.com/python-cmd2/cmd2/blob/main/examples/custom_types.py)
+    - Some useful custom argument types
 - [default_categories.py](https://github.com/python-cmd2/cmd2/blob/main/examples/default_categories.py)
     - Demonstrates usage of `@with_default_category` decorator to group and categorize commands and
       `CommandSet` use