cmd2 3.3.0__tar.gz → 4.0.0b1__tar.gz

{cmd2-3.3.0 → cmd2-4.0.0b1}/.pre-commit-config.yaml

@@ -9,7 +9,7 @@ repos:
       - id: trailing-whitespace
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: "v0.15.0"
+    rev: "v0.15.4"
     hooks:
       - id: ruff-format
         args: [--config=ruff.toml]

{cmd2-3.3.0 → cmd2-4.0.0b1}/CHANGELOG.md

@@ -1,4 +1,97 @@
-# 3.3.0 (March 1, 2026)
+## 4.0.0 (TBD 2026)
+
+### Summary
+
+`cmd2` now has a dependency on
+[prompt-toolkit](https://github.com/prompt-toolkit/python-prompt-toolkit) which serves as a
+pure-Python cross-platform replacement for
+[GNU Readline](https://tiswww.case.edu/php/chet/readline/rltop.html). Previously, `cmd2` had used
+different `readline` dependencies on each Operating System (OS) which was at times a very
+frustrating developer and user experience due to small inconsistencies in these different readline
+libraries. Now we have consistent cross-platform support for tab-completion, user terminal input,
+and history. Additionally, this opens up some cool advanced features such as support for syntax
+highlighting of user input while typing, auto-suggestions similar to those provided by the fish
+shell, and the option for a persistent bottom bar that can display realtime status updates while the
+prompt is displayed.
+
+### Details
+
+- Breaking Changes
+    - Removed all use of `readline` built-in module and underlying platform libraries
+    - Deleted `cmd2.rl_utils` module which dealt with importing the proper `readline` module for
+      each platform and provided utility functions related to `readline`
+    - Added a dependency on `prompt-toolkit` and a new `cmd2.pt_utils` module with supporting
+      utilities
+    - Removed **Transcript Testing** feature set along with the `history -t` option for generating
+      transcript files and the `cmd2.transcript` module
+        - This was an extremely brittle regression testing framework which should never have been
+          built into cmd2
+        - We recommend using [pytest](https://docs.pytest.org/) for unit and integration tests and
+          [Robot Framework](https://robotframework.org/) for acceptance tests. Both of these
+          frameworks can be used to create tests which are far more reliable and less brittle.
+    - Async specific: `prompt-toolkit` starts its own `asyncio` event loop in every `cmd2`
+      application
+        - Removed `cmd2.Cmd.terminal_lock` as it is no longer required to support things like
+          `cmd2.Cmd.async_alert`
+        - Removed `cmd2.Cmd.async_refresh_prompt` and `cmd2.Cmd.need_prompt_refresh` as they are no
+          longer needed
+    - `completer` functions must now return a `cmd2.Completions` object instead of `list[str]`.
+    - `choices_provider` functions must now return a `cmd2.Choices` object instead of `list[str]`.
+    - An argparse argument's `descriptive_headers` field is now called `table_header`.
+    - `CompletionItem.descriptive_data` is now called `CompletionItem.table_row`.
+    - `Cmd.default_sort_key` moved to `utils.DEFAULT_STR_SORT_KEY`.
+    - Moved completion state data, which previously resided in `Cmd`, into other classes.
+        - `Cmd.matches_sorted` -> `Completions.is_sorted` and `Choices.is_sorted`
+        - `Cmd.completion_hint` -> `Completions.completion_hint`
+        - `Cmd.formatted_completions` -> `Completions.completion_table`
+        - `Cmd.allow_appended_space/allow_closing_quote` -> `Completions.allow_finalization`
+    - Removed `Cmd.matches_delimited` since it's no longer used.
+    - Removed `flag_based_complete` and `index_based_complete` functions since their functionality
+      is already provided in arpgarse-based completion.
+    - Changed `Statement.multiline_command` from a string to a bool.
+    - Made `Statement.arg_list` a property which generates the list on-demand.
+    - Renamed `Statement.output` to `Statement.redirector`.
+    - Renamed `Statement.output_to` to `Statement.redirect_to`.
+    - Removed `Statement.pipe_to` since it can be handled by `Statement.redirector` and
+      `Statement.redirect_to`.
+    - Changed `StatementParser.parse_command_only()` to return a `PartialStatement` object.
+    - Renamed `Macro.arg_list` to `Macro.args`.
+    - Removed `terminal_utils.py` since `prompt-toolkit` provides this functionality.
+    - Replaced `async_alert()` and `async_update_prompt()` with a single function called
+      `add_alert()`. This new function is thread-safe and does not require you to acquire a mutex
+      before calling it like the previous functions did.
+    - Removed `Cmd.default_to_shell`.
+- Enhancements
+    - New `cmd2.Cmd` parameters
+        - **auto_suggest**: (boolean) if `True`, provide fish shell style auto-suggestions. These
+          are grayed-out hints based on history. User can press right-arrow key to accept the
+          provided suggestion.
+        - **bottom toolbar**: (boolean) if `True`, present a persistent bottom toolbar capable of
+          displaying realtime status information while the prompt is displayed, see the
+          `cmd2.Cmd2.get_bottom_toolbar` method that can be overridden as well as the updated
+          `getting_started.py` example
+    - New `cmd2.Cmd` methods
+        - **get_bottom_toolbar**: populates bottom toolbar if `bottom_toolbar` is `True`
+        - **get_rprompt**: override to populate right prompt
+        - **pre_prompt**: hook method that is called before the prompt is displayed, but after
+          `prompt-toolkit` event loop has started
+    - New settables:
+        - **max_column_completion_results**: (int) the maximum number of completion results to
+          display in a single column
+
+## 3.4.0 (March 3, 2026)
+
+- Enhancements
+    - Moved cmd2-specific printing logic from `Cmd.print_to()` into `Cmd2BaseConsole.print()` and
+      `Cmd2BaseConsole.log()`. This removes need to pass a console object to `Cmd.print_to()`.
+    - Addressed a bug in `rich.console.Console` where complex renderables (like `Table` and `Rule`)
+      may not receive formatting settings passed to `console.print()` and `console.log()`.
+
+- Breaking Changes
+    - Renamed the `destination` parameter of `Cmd.print_to()` back to `file` since you can no longer
+      pass in a console.
+
+## 3.3.0 (March 1, 2026)
 
 - Enhancements
     - Added ability to pass a console object to `Cmd.print_to()`. This provides support for things

{cmd2-3.3.0 → cmd2-4.0.0b1}/Makefile

@@ -77,7 +77,8 @@ publish: validate-tag build ## Publish a release to PyPI, uses token from ~/.pyp
 BUILD_DIRS = build dist *.egg-info
 DOC_DIRS = build
 MYPY_DIRS = .mypy_cache dmypy.json dmypy.sock
-TEST_DIRS = .cache .coverage .pytest_cache htmlcov
+TEST_DIRS = .cache .pytest_cache htmlcov
+TEST_FILES = .coverage coverage.xml
 
 .PHONY: clean-build
 clean-build: ## Clean build artifacts
@@ -108,6 +109,7 @@ clean-ruff: ## Clean ruff artifacts
 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)]"
+	@uv run python -c "from pathlib import Path; [Path(f).unlink(missing_ok=True) for f in '$(TEST_FILES)'.split()]"
 
 .PHONY: clean
 clean: clean-build clean-docs clean-mypy clean-pycache clean-ruff clean-test ## Clean all artifacts

{cmd2-3.3.0 → cmd2-4.0.0b1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cmd2
-Version: 3.3.0
+Version: 4.0.0b1
 Summary: cmd2 - quickly build feature-rich and user-friendly interactive command line applications in Python
 Author: cmd2 Contributors
 License-Expression: MIT
@@ -23,9 +23,8 @@ Requires-Python: >=3.10
 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: prompt-toolkit>=3.0.52
 Requires-Dist: pyperclip>=1.8.2
-Requires-Dist: pyreadline3>=3.4; platform_system == "Windows"
 Requires-Dist: rich>=14.3.0
 Requires-Dist: rich-argparse>=1.7.1
 Requires-Dist: typing-extensions; python_version == "3.10"
@@ -58,7 +57,7 @@ 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` 3.0.0 has been released and there are some significant backwards
+> :warning: **`cmd2` `3.x` 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.**
@@ -110,8 +109,6 @@ command line argument parsing and execution of cmd2 scripting.
 - Text file scripting of your application with `run_script` (`@`) and `_relative_run_script` (`@@`)
 - Powerful and flexible built-in Python scripting of your application using the `run_pyscript`
   command
-- Transcripts for use with built-in regression can be automatically generated from `history -t` or
-  `run_script -t`
 
 ## Installation
 

{cmd2-3.3.0 → cmd2-4.0.0b1}/README.md

@@ -25,7 +25,7 @@ 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` 3.0.0 has been released and there are some significant backwards
+> :warning: **`cmd2` `3.x` 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.**
@@ -77,8 +77,6 @@ command line argument parsing and execution of cmd2 scripting.
 - Text file scripting of your application with `run_script` (`@`) and `_relative_run_script` (`@@`)
 - Powerful and flexible built-in Python scripting of your application using the `run_pyscript`
   command
-- Transcripts for use with built-in regression can be automatically generated from `history -t` or
-  `run_script -t`
 
 ## Installation
 

{cmd2-3.3.0 → cmd2-4.0.0b1}/cmd2/__init__.py

@@ -15,7 +15,6 @@ from .argparse_completer import set_default_ap_completer_type
 from .argparse_custom import (
     Cmd2ArgumentParser,
     Cmd2AttributeWrapper,
-    CompletionItem,
     register_argparse_argument_parameter,
     set_default_argument_parser_type,
 )
@@ -25,6 +24,11 @@ from .command_definition import (
     CommandSet,
     with_default_category,
 )
+from .completion import (
+    Choices,
+    CompletionItem,
+    Completions,
+)
 from .constants import (
     COMMAND_NAME,
     DEFAULT_SHORTCUTS,
@@ -48,10 +52,10 @@ from .rich_utils import RichPrintKwargs
 from .string_utils import stylize
 from .styles import Cmd2Style
 from .utils import (
-    CompletionMode,
     CustomCompletionSettings,
     Settable,
     categorize,
+    set_default_str_sort_key,
 )
 
 __all__: list[str] = [  # noqa: RUF022
@@ -60,7 +64,6 @@ __all__: list[str] = [  # noqa: RUF022
     # Argparse Exports
     'Cmd2ArgumentParser',
     'Cmd2AttributeWrapper',
-    'CompletionItem',
     'register_argparse_argument_parameter',
     'set_default_ap_completer_type',
     'set_default_argument_parser_type',
@@ -71,6 +74,10 @@ __all__: list[str] = [  # noqa: RUF022
     'Statement',
     # Colors
     "Color",
+    # Completion
+    'Choices',
+    'CompletionItem',
+    'Completions',
     # Decorators
     'with_argument_list',
     'with_argparser',
@@ -95,7 +102,7 @@ __all__: list[str] = [  # noqa: RUF022
     "Cmd2Style",
     # Utilities
     'categorize',
-    'CompletionMode',
     'CustomCompletionSettings',
     'Settable',
+    'set_default_str_sort_key',
 ]