cmd2 3.4.0__tar.gz → 4.0.0b2__tar.gz

{cmd2-3.4.0 → cmd2-4.0.0b2}/.pre-commit-config.yaml

@@ -3,13 +3,18 @@ repos:
     rev: "v6.0.0"
     hooks:
       - id: check-case-conflict
+      - id: check-executables-have-shebangs
       - id: check-merge-conflict
       - id: check-toml
+      - id: check-yaml
+      - id: detect-private-key
       - id: end-of-file-fixer
+      - id: fix-byte-order-marker
+      - id: mixed-line-ending
       - id: trailing-whitespace
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: "v0.15.0"
+    rev: "v0.15.6"
     hooks:
       - id: ruff-format
         args: [--config=ruff.toml]
@@ -23,3 +28,13 @@ repos:
         additional_dependencies:
           - prettier@3.8.1
           - prettier-plugin-toml@2.0.6
+
+  - repo: https://github.com/crate-ci/typos
+    rev: v1.44.0
+    hooks:
+      - id: typos
+        exclude: |
+          (?x)^(
+            ruff.toml|
+            tests/.*
+          )$

cmd2-4.0.0b2/.typos.toml

@@ -0,0 +1,5 @@
+[default.extend-words]
+EXPLIoT = "EXPLIoT"
+Counterfit = "Counterfit"
+expliot = "expliot"
+counterfit = "counterfit"

{cmd2-3.4.0 → cmd2-4.0.0b2}/CHANGELOG.md

@@ -1,3 +1,94 @@
+## 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_columns`.
+    - `CompletionItem.descriptive_data` is now called `CompletionItem.table_data`.
+    - Removed `DEFAULT_DESCRIPTIVE_HEADERS`. This means you must define `table_columns` when using
+      `CompletionItem.table_data` data.
+    - `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.hint`
+        - `Cmd.formatted_completions` -> `Completions.table` (Now a Rich 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`.
+    - Removed `Cmd.ruler` since `cmd2` no longer uses it.
+- 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
+        - **read_secret**: read secrets like passwords without displaying them to the terminal
+    - New settables:
+        - **max_column_completion_results**: (int) the maximum number of completion results to
+          display in a single column
+    - `cmd2.Cmd.select` has been revamped to use the
+      [choice](https://python-prompt-toolkit.readthedocs.io/en/3.0.52/pages/asking_for_a_choice.html)
+      function from `prompt-toolkit` when both **stdin** and **stdout** are TTYs
+    - Add support for Python 3.15 by fixing various bugs related to internal `argparse` changes
+    - Added `common_prefix` method to `cmd2.string_utils` module as a replacement for
+      `os.path.commonprefix` since that is now deprecated in Python 3.15
+
 ## 3.4.0 (March 3, 2026)
 
 - Enhancements

{cmd2-3.4.0 → cmd2-4.0.0b2}/Makefile

@@ -7,8 +7,8 @@ install: ## Install the virtual environment with dependencies
 	@echo "🚀 Creating uv Python virtual environment"
 	@uv python install 3.14
 	@uv sync --python=3.14
-	@echo "🚀 Installing Git pre-commit hooks locally"
-	@uv run pre-commit install
+	@echo "🚀 Installing Git prek hooks locally"
+	@uv run prek install -f
 	@echo "🚀 Installing Prettier using npm"
 	@npm install -q --no-fund --include=dev
 
@@ -16,8 +16,8 @@ install: ## Install the virtual environment with dependencies
 check: ## Run code quality tools.
 	@echo "🚀 Checking lock file consistency with 'pyproject.toml'"
 	@uv lock --locked
-	@echo "🚀 Linting code and documentation: Running pre-commit"
-	@uv run pre-commit run -a
+	@echo "🚀 Auto-formatting/Linting code and documentation: Running prek"
+	@uv run prek run -a
 	@echo "🚀 Static type checking: Running mypy"
 	@uv run mypy
 
@@ -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.4.0 → cmd2-4.0.0b2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cmd2
-Version: 3.4.0
+Version: 4.0.0b2
 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
 
@@ -142,7 +139,7 @@ examples.
 - [cmd2 example applications](https://github.com/python-cmd2/cmd2/tree/main/examples)
     - Basic cmd2 examples to demonstrate how to use various features
 - [Advanced Examples](https://github.com/jayrod/cmd2-example-apps)
-    - More complex examples that demonstrate more featuers about how to put together a complete
+    - More complex examples that demonstrate more features about how to put together a complete
       application
 - [Cookiecutter](https://github.com/cookiecutter/cookiecutter) Templates from community
     - Basic cookiecutter template for cmd2 application :

{cmd2-3.4.0 → cmd2-4.0.0b2}/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
 
@@ -109,7 +107,7 @@ examples.
 - [cmd2 example applications](https://github.com/python-cmd2/cmd2/tree/main/examples)
     - Basic cmd2 examples to demonstrate how to use various features
 - [Advanced Examples](https://github.com/jayrod/cmd2-example-apps)
-    - More complex examples that demonstrate more featuers about how to put together a complete
+    - More complex examples that demonstrate more features about how to put together a complete
       application
 - [Cookiecutter](https://github.com/cookiecutter/cookiecutter) Templates from community
     - Basic cookiecutter template for cmd2 application :

{cmd2-3.4.0 → cmd2-4.0.0b2}/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',
@@ -92,10 +99,10 @@ __all__: list[str] = [  # noqa: RUF022
     # String Utils
     'stylize',
     # Styles,
-    "Cmd2Style",
+    'Cmd2Style',
     # Utilities
     'categorize',
-    'CompletionMode',
     'CustomCompletionSettings',
     'Settable',
+    'set_default_str_sort_key',
 ]