cmd2 3.0.0rc1__tar.gz → 3.1.1__tar.gz

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

@@ -9,7 +9,7 @@ repos:
       - id: trailing-whitespace
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: "v0.13.2"
+    rev: "v0.14.14"
     hooks:
       - id: ruff-format
         args: [--config=ruff.toml]
@@ -21,5 +21,5 @@ repos:
     hooks:
       - id: prettier
         additional_dependencies:
-          - prettier@3.6.2
+          - prettier@3.8.0
           - prettier-plugin-toml@2.0.6

cmd2-3.1.1/.prettierignore

@@ -0,0 +1,5 @@
+# File is nicely lined up
+.github/CODEOWNERS
+
+# Markdown documentation files with non-standard syntax for mkdocstrings that Prettier should not auto-format
+docs/features/initialization.md

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

@@ -1,4 +1,16 @@
-## 3.0.0 (October TBD, 2025)
+## 3.1.1 (January 26, 2026)
+
+- Bug Fixes
+    - Fixed bug where `rich-argparse` was not coloring cmd2's custom `nargs` formatting
+
+## 3.1.0 (December 25, 2025)
+
+- Potentially Breaking Changes
+    - `cmd2` no longer has a dependency on `cmd` and `cmd2.Cmd` no longer inherits from `cmd.Cmd`
+        - We don't _think_ this should impact users, but there is theoretically a possibility
+        - This opens the door for more impactful changes in the next major release
+
+## 3.0.0 (December 7, 2025)
 
 ### Summary
 
@@ -16,6 +28,8 @@ time reading the [rich documentation](https://rich.readthedocs.io/).
           [rich_tables.py](https://github.com/python-cmd2/cmd2/blob/main/examples/rich_tables.py)
           example for more info)
         - Moved all string-related functions from `utils.py` to a new `string_utils.py` module
+            - Removed redundant `string` from some of the names so `quote_string` is now just
+              `quote` and `quote_string_if_needed` is now `quote_if_needed`
         - Consolidated all string styling functions from `ansi.py` into `string_utils.py`
         - Replaced all text style enums from `ansi.py` with modern `rich` styles
         - Renamed `ansi.py` to `terminal_utils.py` to better reflect its purpose
@@ -25,6 +39,20 @@ time reading the [rich documentation](https://rich.readthedocs.io/).
     - 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`
+    - `argparse_custom` module breaking changes:
+        - `descriptive_header: str` replaced with `descriptive_headers: Sequence[str | rich.Column]`
+            - Applies to parameter name when adding an argument to a parser as well as
+              `set_descriptive_headers` and `get_descriptive_headers`
+        - `CompletionItem.description: str` changed to
+          `CompletionItem.descriptive_data: Sequence[str | rich.Column]`
+    - `decorators` module breaking changes:
+        - `_set_parser_prog` renamed to `set_parser_prog` (without the leading underscore) and moved
+          to `argparse_custom` module
+    - Renamed history `--output_file` to `--output-file` to follow common command-line practices
+    - `cmd2.Cmd.ppretty` method removed - `rich` has more and better options for pretty printing,
+      see the
+      [pretty_print.py](https://github.com/python-cmd2/cmd2/blob/main/examples/pretty_print.py)
+      example for a demonstration of pretty-printing JSON data
 
 - Enhancements
     - Enhanced all print methods (`poutput()`, `perror()`, `ppaged()`, etc.) to natively render

cmd2-3.1.1/LICENSE

@@ -0,0 +1,18 @@
+The MIT License (MIT)
+
+Copyright (c) 2008-2026 Catherine Devlin and others
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
+associated documentation files (the "Software"), to deal in the Software without restriction,
+including without limitation the rights to use, copy, modify, merge, publish, distribute,
+sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial
+portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT
+NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES
+OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

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

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

{cmd2-3.0.0rc1 → cmd2-3.1.1}/Makefile

@@ -1,9 +1,12 @@
 # Simple Makefile for use with a uv-based development environment
+# The at (@) prefix tells make to suppress output from the command
+# The hyphen (-) prefix tells make to ignore errors (e.g., if a directory doesn't exist)
+
 .PHONY: install
 install: ## Install the virtual environment with dependencies
 	@echo "🚀 Creating uv Python virtual environment"
-	@uv python install 3.13
-	@uv sync --python=3.13
+	@uv python install 3.14
+	@uv sync --python=3.14
 	@echo "🚀 Installing Git pre-commit hooks locally"
 	@uv run pre-commit install
 	@echo "🚀 Installing Prettier using npm"
@@ -37,21 +40,16 @@ test: ## Test the code with pytest.
 
 .PHONY: docs-test
 docs-test: ## Test if documentation can be built without warnings or errors
-	@uv run mkdocs build -s
+	@uv run zensical build -s
 
 .PHONY: docs
-docs: ## Build and serve the documentation
-	@uv run mkdocs serve
+docs: ## Build and serve the documentation (and open in default browser)
+	@uv run zensical serve -o
 
 .PHONY: build
 build: clean-build ## Build wheel file
 	@echo "🚀 Creating wheel file"
-	@uvx --from build pyproject-build --installer uv
-
-.PHONY: clean-build
-clean-build: ## Clean build artifacts
-	@echo "🚀 Removing build artifacts"
-	@uv run python -c "import shutil; import os; shutil.rmtree('dist') if os.path.exists('dist') else None"
+	@uv build
 
 .PHONY: tag
 tag: ## Add a Git tag and push it to origin with syntax: make tag TAG=tag_name
@@ -63,17 +61,57 @@ tag: ## Add a Git tag and push it to origin with syntax: make tag TAG=tag_name
 .PHONY: validate-tag
 validate-tag: ## Check to make sure that a tag exists for the current HEAD and it looks like a valid version number
 	@echo "🚀 Validating version tag"
-	@uv run inv validatetag
+	@uv run scripts/validate_tag.py
 
 .PHONY: publish-test
-publish-test: validate-tag build ## Test publishing a release to PyPI.
+publish-test: validate-tag build ## Test publishing a release to PyPI, uses token from ~/.pypirc file.
 	@echo "🚀 Publishing: Dry run."
-	@uvx twine upload --repository testpypi dist/*
+	@uv run uv-publish --repository testpypi
 
 .PHONY: publish
-publish: validate-tag build ## Publish a release to PyPI.
+publish: validate-tag build ## Publish a release to PyPI, uses token from ~/.pypirc file.
 	@echo "🚀 Publishing."
-	@uvx twine upload dist/*
+	@uv run uv-publish
+
+# Define variables for files/directories to clean
+BUILD_DIRS = build dist *.egg-info
+DOC_DIRS = build
+MYPY_DIRS = .mypy_cache dmypy.json dmypy.sock
+TEST_DIRS = .cache .coverage .pytest_cache htmlcov
+
+.PHONY: clean-build
+clean-build: ## Clean build artifacts
+	@echo "🚀 Removing build artifacts"
+	@uv run python -c "import shutil; import os; [shutil.rmtree(d, ignore_errors=True) for d in '$(BUILD_DIRS)'.split() if os.path.isdir(d)]"
+
+.PHONY: clean-docs
+clean-docs: ## Clean documentation artifacts
+	@echo "🚀 Removing documentation artifacts"
+	@uv run python -c "import shutil; import os; [shutil.rmtree(d, ignore_errors=True) for d in '$(DOC_DIRS)'.split() if os.path.isdir(d)]"
+
+.PHONY: clean-mypy
+clean-mypy: ## Clean mypy artifacts
+	@echo "🚀 Removing mypy artifacts"
+	@uv run python -c "import shutil; import os; [shutil.rmtree(d, ignore_errors=True) for d in '$(MYPY_DIRS)'.split() if os.path.isdir(d)]"
+
+.PHONY: clean-pycache
+clean-pycache: ## Clean pycache artifacts
+	@echo "🚀 Removing pycache artifacts"
+	@-find . -type d -name "__pycache__" -exec rm -r {} +
+
+.PHONY: clean-ruff
+clean-ruff: ## Clean ruff artifacts
+	@echo "🚀 Removing ruff artifacts"
+	@uv run ruff clean
+
+.PHONY: clean-test
+clean-test: ## Clean test artifacts
+	@echo "🚀 Removing test artifacts"
+	@uv run python -c "import shutil; import os; [shutil.rmtree(d, ignore_errors=True) for d in '$(TEST_DIRS)'.split() if os.path.isdir(d)]"
+
+.PHONY: clean
+clean: clean-build clean-docs clean-mypy clean-pycache clean-ruff clean-test ## Clean all artifacts
+	@echo "🚀 Cleaned all artifacts"
 
 .PHONY: help
 help:

{cmd2-3.0.0rc1 → cmd2-3.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cmd2
-Version: 3.0.0rc1
+Version: 3.1.1
 Summary: cmd2 - quickly build feature-rich and user-friendly interactive command line applications in Python
 Author: cmd2 Contributors
 License-Expression: MIT
@@ -16,6 +16,7 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
 Classifier: Programming Language :: Python :: Free Threading :: 3 - Stable
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.10
@@ -23,16 +24,16 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: backports.strenum; python_version == "3.10"
 Requires-Dist: gnureadline>=8; platform_system == "Darwin"
-Requires-Dist: pyperclip>=1.8
+Requires-Dist: pyperclip>=1.8.2
 Requires-Dist: pyreadline3>=3.4; platform_system == "Windows"
-Requires-Dist: rich>=14.1.0
+Requires-Dist: rich>=14.3.0
 Requires-Dist: rich-argparse>=1.7.1
 Dynamic: license-file
 
 <h1 align="center">cmd2 : immersive interactive command line applications</h1>
 
 [![Latest Version](https://img.shields.io/pypi/v/cmd2.svg?style=flat-square&label=latest%20stable%20version)](https://pypi.python.org/pypi/cmd2/)
-[![GitHub Actions](https://github.com/python-cmd2/cmd2/workflows/CI/badge.svg)](https://github.com/python-cmd2/cmd2/actions?query=workflow%3ACI)
+[![Tests](https://github.com/python-cmd2/cmd2/actions/workflows/tests.yml/badge.svg)](https://github.com/python-cmd2/cmd2/actions/workflows/tests.yml)
 [![codecov](https://codecov.io/gh/python-cmd2/cmd2/branch/main/graph/badge.svg)](https://codecov.io/gh/python-cmd2/cmd2)
 [![Documentation Status](https://readthedocs.org/projects/cmd2/badge/?version=latest)](http://cmd2.readthedocs.io/en/latest/?badge=latest)
 <a href="https://discord.gg/RpVG6tk"><img src="https://img.shields.io/badge/chat-on%20discord-7289da.svg" alt="Chat"></a>
@@ -56,10 +57,10 @@ applications. It provides a simple API which is an extension of Python's built-i
 of cmd to make your life easier and eliminates much of the boilerplate code which would be necessary
 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. A beta version, 3.0.0b2, is available for testing and we
-> would appreciate feedback.**
+> :warning: **`cmd2` 3.0.0 has been released and there are some significant backwards
+> incompatibilities from version `2.x`. Please see the
+> [Migration Guide](https://cmd2.readthedocs.io/en/latest/upgrades/) for tips on upgrading from
+> `cmd2` 2.x to 3.x.**
 
 ## The developers toolbox
 

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

@@ -1,7 +1,7 @@
 <h1 align="center">cmd2 : immersive interactive command line applications</h1>
 
 [![Latest Version](https://img.shields.io/pypi/v/cmd2.svg?style=flat-square&label=latest%20stable%20version)](https://pypi.python.org/pypi/cmd2/)
-[![GitHub Actions](https://github.com/python-cmd2/cmd2/workflows/CI/badge.svg)](https://github.com/python-cmd2/cmd2/actions?query=workflow%3ACI)
+[![Tests](https://github.com/python-cmd2/cmd2/actions/workflows/tests.yml/badge.svg)](https://github.com/python-cmd2/cmd2/actions/workflows/tests.yml)
 [![codecov](https://codecov.io/gh/python-cmd2/cmd2/branch/main/graph/badge.svg)](https://codecov.io/gh/python-cmd2/cmd2)
 [![Documentation Status](https://readthedocs.org/projects/cmd2/badge/?version=latest)](http://cmd2.readthedocs.io/en/latest/?badge=latest)
 <a href="https://discord.gg/RpVG6tk"><img src="https://img.shields.io/badge/chat-on%20discord-7289da.svg" alt="Chat"></a>
@@ -25,10 +25,10 @@ applications. It provides a simple API which is an extension of Python's built-i
 of cmd to make your life easier and eliminates much of the boilerplate code which would be necessary
 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. A beta version, 3.0.0b2, is available for testing and we
-> would appreciate feedback.**
+> :warning: **`cmd2` 3.0.0 has been released and there are some significant backwards
+> incompatibilities from version `2.x`. Please see the
+> [Migration Guide](https://cmd2.readthedocs.io/en/latest/upgrades/) for tips on upgrading from
+> `cmd2` 2.x to 3.x.**
 
 ## The developers toolbox
 

{cmd2-3.0.0rc1 → cmd2-3.1.1}/cmd2/argparse_completer.py

@@ -39,7 +39,7 @@ from .exceptions import CompletionError
 from .styles import Cmd2Style
 
 # If no descriptive headers are supplied, then this will be used instead
-DEFAULT_DESCRIPTIVE_HEADERS: Sequence[str | Column] = ('Description',)
+DEFAULT_DESCRIPTIVE_HEADERS: Sequence[str | Column] = ['Description']
 
 # Name of the choice/completer function argument that, if present, will be passed a dictionary of
 # command line tokens up through the token being completed mapped to their argparse destination name.

{cmd2-3.0.0rc1 → cmd2-3.1.1}/cmd2/argparse_custom.py

@@ -258,14 +258,11 @@ sub-parser from a sub-parsers group. See _SubParsersAction_remove_parser` for mo
 import argparse
 import re
 import sys
-from argparse import (
-    ONE_OR_MORE,
-    ZERO_OR_MORE,
-    ArgumentError,
-)
+from argparse import ArgumentError
 from collections.abc import (
     Callable,
     Iterable,
+    Iterator,
     Sequence,
 )
 from gettext import gettext
@@ -293,6 +290,7 @@ from rich_argparse import (
     RawTextRichHelpFormatter,
     RichHelpFormatter,
 )
+from typing_extensions import Self
 
 from . import constants
 from . import rich_utils as ru
@@ -380,7 +378,7 @@ class CompletionItem(str):  # noqa: SLOT000
     See header of this file for more information
     """
 
-    def __new__(cls, value: object, *_args: Any, **_kwargs: Any) -> 'CompletionItem':
+    def __new__(cls, value: object, *_args: Any, **_kwargs: Any) -> Self:
         """Responsible for creating and returning a new instance, called before __init__ when an object is instantiated."""
         return super().__new__(cls, value)
 
@@ -804,7 +802,7 @@ def _add_argument_wrapper(
     choices_provider: ChoicesProviderFunc | None = None,
     completer: CompleterFunc | None = None,
     suppress_tab_hint: bool = False,
-    descriptive_headers: list[Column | str] | None = None,
+    descriptive_headers: Sequence[str | Column] | None = None,
     **kwargs: Any,
 ) -> argparse.Action:
     """Wrap ActionsContainer.add_argument() which supports more settings used by cmd2.
@@ -1295,29 +1293,68 @@ class Cmd2HelpFormatter(RichHelpFormatter):
 
         return format_tuple
 
+    def _build_nargs_range_str(self, nargs_range: tuple[int, int | float]) -> str:
+        """Generate nargs range string for help text."""
+        if nargs_range[1] == constants.INFINITY:
+            # {min+}
+            range_str = f"{{{nargs_range[0]}+}}"
+        else:
+            # {min..max}
+            range_str = f"{{{nargs_range[0]}..{nargs_range[1]}}}"
+
+        return range_str
+
     def _format_args(self, action: argparse.Action, default_metavar: str) -> str:
-        """Handle ranged nargs and make other output less verbose."""
+        """Override to handle cmd2's custom nargs formatting.
+
+        All formats in this function need to be handled by _rich_metavar_parts().
+        """
         metavar = self._determine_metavar(action, default_metavar)
         metavar_formatter = self._metavar_formatter(action, default_metavar)
 
         # Handle nargs specified as a range
         nargs_range = action.get_nargs_range()  # type: ignore[attr-defined]
         if nargs_range is not None:
-            range_str = f'{nargs_range[0]}+' if nargs_range[1] == constants.INFINITY else f'{nargs_range[0]}..{nargs_range[1]}'
-
-            return '{}{{{}}}'.format('%s' % metavar_formatter(1), range_str)  # noqa: UP031
-
-        # Make this output less verbose. Do not customize the output when metavar is a
-        # tuple of strings. Allow argparse's formatter to handle that instead.
-        if isinstance(metavar, str):
-            if action.nargs == ZERO_OR_MORE:
-                return '[%s [...]]' % metavar_formatter(1)  # noqa: UP031
-            if action.nargs == ONE_OR_MORE:
-                return '%s [...]' % metavar_formatter(1)  # noqa: UP031
-            if isinstance(action.nargs, int) and action.nargs > 1:
-                return '{}{{{}}}'.format('%s' % metavar_formatter(1), action.nargs)  # noqa: UP031
+            arg_str = '%s' % metavar_formatter(1)  # noqa: UP031
+            range_str = self._build_nargs_range_str(nargs_range)
+            return f"{arg_str}{range_str}"
+
+        # When nargs is just a number, argparse repeats the arg in the help text.
+        # For instance, when nargs=5 the help text looks like: 'command arg arg arg arg arg'.
+        # To make this less verbose, format it like: 'command arg{5}'.
+        # Do not customize the output when metavar is a tuple of strings. Allow argparse's
+        # formatter to handle that instead.
+        if isinstance(metavar, str) and isinstance(action.nargs, int) and action.nargs > 1:
+            arg_str = '%s' % metavar_formatter(1)  # noqa: UP031
+            return f"{arg_str}{{{action.nargs}}}"
+
+        # Fallback to parent for all other cases
+        return super()._format_args(action, default_metavar)
+
+    def _rich_metavar_parts(
+        self,
+        action: argparse.Action,
+        default_metavar: str,
+    ) -> Iterator[tuple[str, bool]]:
+        """Override to handle all cmd2-specific formatting in _format_args()."""
+        metavar = self._determine_metavar(action, default_metavar)
+        metavar_formatter = self._metavar_formatter(action, default_metavar)
 
-        return super()._format_args(action, default_metavar)  # type: ignore[arg-type]
+        # Handle nargs specified as a range
+        nargs_range = action.get_nargs_range()  # type: ignore[attr-defined]
+        if nargs_range is not None:
+            yield "%s" % metavar_formatter(1), True  # noqa: UP031
+            yield self._build_nargs_range_str(nargs_range), False
+            return
+
+        # Handle specific integer nargs (e.g., nargs=5 -> arg{5})
+        if isinstance(metavar, str) and isinstance(action.nargs, int) and action.nargs > 1:
+            yield "%s" % metavar_formatter(1), True  # noqa: UP031
+            yield f"{{{action.nargs}}}", False
+            return
+
+        # Fallback to parent for all other cases
+        yield from super()._rich_metavar_parts(action, default_metavar)
 
 
 class RawDescriptionCmd2HelpFormatter(