cmd2 4.0.0rc2__tar.gz → 4.1.0__tar.gz

{cmd2-4.0.0rc2 → cmd2-4.1.0}/.pre-commit-config.yaml

@@ -14,7 +14,7 @@ repos:
       - id: trailing-whitespace
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: "v0.15.15"
+    rev: "v0.15.17"
     hooks:
       - id: ruff-format
         args: [--config=ruff.toml]
@@ -30,7 +30,7 @@ repos:
           - prettier-plugin-toml@2.0.6
 
   - repo: https://github.com/crate-ci/typos
-    rev: v1.47.0
+    rev: v1.47.2
     hooks:
       - id: typos
         exclude: |

{cmd2-4.0.0rc2 → cmd2-4.1.0}/CHANGELOG.md

@@ -1,4 +1,75 @@
-## 4.0.0 (June TBD, 2026)
+## 4.1.0 (July 7, 2026)
+
+- Breaking Changes
+    - Renamed the `bottom_toolbar` argument in `Cmd.__init__()` to `enable_bottom_toolbar`. It is
+      also now strictly an `__init__` parameter and not an instance attribute.
+    - `complete_in_thread` is now strictly an `__init__` parameter and not an instance attribute of
+      `Cmd`.
+    - `get_rprompt()` is now only called if the `enable_rprompt` argument in `Cmd.__init__()` is set
+      to `True`.
+- Bug Fixes
+    - Fixed type hinting so that methods decorated with `with_annotated` no longer trigger spurious
+      mypy errors and preserve their original signature.
+    - Fixed cmd2 bypassing NO_COLOR and allow_style when setting prompt-toolkit's color depth.
+- Enhancements
+    - New `cmd2.Cmd` parameters
+        - **complete_in_thread**: (boolean) if `True`, then completion will run in a separate
+          thread. If `False` then completion runs in the main thread and causes it to block if slow.
+          Defaults to `True`.
+        - **refresh_interval**: (float) How often, in seconds, to automatically refresh the UI.
+          Defaults to 0.0. This is used for bottom toolbars and right prompts which have dynamic
+          content needing to be refreshed at regular intervals and not just when a key is pressed.
+    - Improved
+      [getting_started.py](https://github.com/python-cmd2/cmd2/blob/main/examples/getting_started.py)
+      example
+        - Shows how to properly and safely use a background thread to update the bottom toolbar with
+          dynamic content
+        - Demonstrates how to use the `@with_argparser` and `@with_argument_block` decorators for
+          parsing command arguments
+- Experimental features
+    - `@with_annotated` now supports `frozenset[T]` collection parameters, alongside the existing
+      `list[T]`, `set[T]`, and `tuple[T, ...]` collection types.
+    - `@with_annotated` mutually exclusive groups now accept a `title`/`description` to render the
+      group as a titled help section (argparse's one supported nesting, a mutex inside an argument
+      group), declared in one place with no paired `groups=` entry.
+    - `@with_annotated` now validates `groups` / `mutually_exclusive_groups` specs eagerly at
+      decoration time, so a misconfigured group (a member that names no parameter, a parameter
+      placed in two groups, a mutex group spanning or partially overlapping argument groups, a
+      titled section declared in two places, or `Group(required=True)` on a plain group) hard-fails
+      when the class is defined instead of being deferred to first command use where the error was
+      swallowed. The checks read parameter names only, so forward-referenced annotations still
+      decorate cleanly.
+    - `Argument`/`Option` accept a new `allow_unknown_entry` flag for `Enum` parameters. When set, a
+      command-line token matched by neither a member value nor name is routed through the enum's own
+      [`_missing_`](https://docs.python.org/3/library/enum.html#enum.Enum._missing_) hook, so an
+      enum can resolve aliases, alternate spellings, or special keywords. A token that `_missing_`
+      declines (returns `None`) is still rejected.
+    - `@with_annotated` now supports a union of `Enum` subclasses (e.g. `EnumA | EnumB`). Each
+      member keeps its own converter and a token resolves to the first member that accepts it, so
+      when two members share a representation the earlier one in the union wins. A member whose
+      `_missing_` raises on a token declines it (the next member is still tried) rather than
+      aborting the union, and a merged "choose from ..." error is raised only when every member
+      declines. Unions containing a `Literal` or any non-`Enum` member are still rejected as
+      ambiguous.
+    - `Argument`/`Option` accept new `converter` and `preprocess` hooks for custom string
+      conversion, giving `@with_annotated` parity with a hand-built `add_argument(type=...)` (a raw
+      `type=` in the metadata is still rejected). `converter` is a `Callable[[str], Any]` that
+      replaces the inferred `type=` converter; because it owns the conversion, the annotation may be
+      any type (an otherwise unsupported type like `datetime`, or an otherwise-ambiguous
+      multi-member union like `int | str`, becomes legal) and the inferred `choices`/completer are
+      dropped. `preprocess` is a `Callable[[str], str]` that runs before the inferred converter,
+      transforming the raw token while keeping the inferred `type=`/`choices`/completer (e.g.
+      `preprocess=str.lower` on an `Enum`). The two are mutually exclusive on one parameter and
+      neither may be combined with a value-less action.
+    - `@with_annotated` now supports reusable argument blocks: a parameter typed with a `@dataclass`
+      that subclasses the new `cmd2.ArgumentBlock` trait expands each field into a flat command-line
+      argument, and the parsed values are reconstructed into a dataclass instance passed to the
+      command, letting several commands reuse the same fields without duplication. See the
+      [annotated](docs/features/annotated.md) documentation.
+    - A command can share an argument block with its subcommands via `cmd2_base_args` /
+      `cmd2_parent_args` parameters, passing parent-level options down without redeclaring them.
+
+## 4.0.0 (June 5, 2026)
 
 ### Summary
 

{cmd2-4.0.0rc2 → cmd2-4.1.0}/GEMINI.md

@@ -13,6 +13,8 @@ Python project, which utilizes `uv` for environment and package management.
     - To run programs directly from a PyPI package (installing it on the fly if necessary), use
       `uvx ...` (shortcut for `uv tool run`).
 - **New Dependencies:** If a new dependency is required, please state the reason for its inclusion.
+- Do not commit spec, plan, or markdown documents to git without asking first.
+- Save plans to `~/.superpowers/plans/` instead of the project directory.
 
 ## Python Code Standards
 

{cmd2-4.0.0rc2 → cmd2-4.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cmd2
-Version: 4.0.0rc2
+Version: 4.1.0
 Summary: cmd2 - quickly build feature-rich and user-friendly interactive command line applications in Python
 Author: cmd2 Contributors
 License-Expression: MIT
@@ -55,7 +55,7 @@ of cmd to make your life easier and eliminates much of the boilerplate code whic
 when using cmd.
 
 > :warning: **If you are upgrading from an older version of `cmd2`, both `3.x` and `4.x` have some
-> significant backwards incompatibilities from version `2.x`. Please see the
+> significant backwards incompatibilities from previous versions. Please see the
 > [CHANGELOG](./CHANGELOG.md) for info on what has changed and the
 > [Migration Guide](https://cmd2.readthedocs.io/en/latest/upgrades/) for tips on upgrading from an
 > older version of `cmd2` to `4.x`**
@@ -183,23 +183,25 @@ reproduce the bug. At a minimum, please state the following:
 
 ## Projects using cmd2
 
-| Application Name                                                | Description                                                                                                                     | Organization or Author                                                |
-| --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
-| [CephFS Shell](https://github.com/ceph/ceph)                    | The Ceph File System, or CephFS, is a POSIX-compliant file system built on top of Ceph’s distributed object store               | [ceph](https://ceph.com/)                                             |
-| [garak](https://github.com/NVIDIA/garak)                        | LLM vulnerability scanner that checks if an LLM can be made to fail in a way we don't want                                      | [NVIDIA](https://github.com/NVIDIA)                                   |
-| [medusa](https://github.com/Ch0pin/medusa)                      | Binary instrumentation framework that that automates processes for the dynamic analysis of Android and iOS Applications         | [Ch0pin](https://github.com/Ch0pin)                                   |
-| [InternalBlue](https://github.com/seemoo-lab/internalblue)      | Bluetooth experimentation framework for Broadcom and Cypress chips                                                              | [Secure Mobile Networking Lab](https://github.com/seemoo-lab)         |
-| [SCCMHunter](https://github.com/garrettfoster13/sccmhunter)     | A post-ex tool built to streamline identifying, profiling, and attacking SCCM related assets in an Active Directory domain      | [Garret Foster](https://github.com/garrettfoster13)                   |
-| [Unipacker](https://github.com/unipacker/unipacker)             | Automatic and platform-independent unpacker for Windows binaries based on emulation                                             | [unipacker](https://github.com/unipacker)                             |
-| [Frankenstein](https://github.com/seemoo-lab/frankenstein)      | Broadcom and Cypress firmware emulation for fuzzing and further full-stack debugging                                            | [Secure Mobile Networking Lab](https://github.com/seemoo-lab)         |
-| [Poseidon](https://github.com/faucetsdn/poseidon)               | Leverages software-defined networks (SDNs) to acquire and then feed network traffic to a number of machine learning techniques. | [Faucet SDN](https://github.com/faucetsdn)                            |
-| [DFTimewolf](https://github.com/log2timeline/dftimewolf)        | A framework for orchestrating forensic collection, processing and data export                                                   | [log2timeline](https://github.com/log2timeline)                       |
-| [GAP SDK](https://github.com/GreenWaves-Technologies/gap_sdk)   | SDK for Greenwaves Technologies' GAP8 IoT Application Processor                                                                 | [GreenWaves Technologies](https://github.com/GreenWaves-Technologies) |
-| [REW Sploit](https://github.com/REW-sploit/REW-sploit)          | Emulate and Dissect Metasploit Framework (MSF) and other attacks                                                                | [REW-sploit](https://github.com/REW-sploit)                           |
-| [tomcatmanager](https://github.com/tomcatmanager/tomcatmanager) | A command line tool and python library for managing a tomcat server                                                             | [tomcatmanager](https://github.com/tomcatmanager)                     |
-| [Falcon Toolkit](https://github.com/CrowdStrike/Falcon-Toolkit) | Unleash the power of the CrowdStrike Falcon Platform at the CLI                                                                 | [CrowdStrike](https://github.com/CrowdStrike)                         |
-| [EXPLIoT](https://gitlab.com/expliot_framework/expliot)         | Internet of Things Security Testing and Exploitation framework                                                                  | [expliot_framework](https://gitlab.com/expliot_framework/)            |
-| [Pobshell](https://github.com/pdalloz/pobshell)                 | A Bash‑like shell for live Python objects: `cd`, `ls`, `cat`, `find` and _CLI piping_ for object code, str values & more        | [Peter Dalloz](https://www.linkedin.com/in/pdalloz)                   |
+| Application Name                                                | Description                                                                                                                      | Organization or Author                                                |
+| --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
+| [CephFS Shell](https://github.com/ceph/ceph)                    | The Ceph File System, or CephFS, is a POSIX-compliant file system built on top of Ceph’s distributed object store                | [ceph](https://ceph.com/)                                             |
+| [garak](https://github.com/NVIDIA/garak)                        | LLM vulnerability scanner that checks if an LLM can be made to fail in a way we don't want                                       | [NVIDIA](https://github.com/NVIDIA)                                   |
+| [Argus](https://github.com/jasonxtn/argus)                      | The Ultimate Information Gathering Toolkit                                                                                       | [JASON13](https://github.com/jasonxtn)                                |
+| [medusa](https://github.com/Ch0pin/medusa)                      | Binary instrumentation framework that that automates processes for the dynamic analysis of Android and iOS Applications          | [Ch0pin](https://github.com/Ch0pin)                                   |
+| [InternalBlue](https://github.com/seemoo-lab/internalblue)      | Bluetooth experimentation framework for Broadcom and Cypress chips                                                               | [Secure Mobile Networking Lab](https://github.com/seemoo-lab)         |
+| [SCCMHunter](https://github.com/garrettfoster13/sccmhunter)     | A post-ex tool built to streamline identifying, profiling, and attacking SCCM related assets in an Active Directory domain       | [Garret Foster](https://github.com/garrettfoster13)                   |
+| [Unipacker](https://github.com/unipacker/unipacker)             | Automatic and platform-independent unpacker for Windows binaries based on emulation                                              | [unipacker](https://github.com/unipacker)                             |
+| [Frankenstein](https://github.com/seemoo-lab/frankenstein)      | Broadcom and Cypress firmware emulation for fuzzing and further full-stack debugging                                             | [Secure Mobile Networking Lab](https://github.com/seemoo-lab)         |
+| [Poseidon](https://github.com/faucetsdn/poseidon)               | Leverages software-defined networks (SDNs) to acquire and then feed network traffic to a number of machine learning techniques.  | [Faucet SDN](https://github.com/faucetsdn)                            |
+| [DFTimewolf](https://github.com/log2timeline/dftimewolf)        | A framework for orchestrating forensic collection, processing and data export                                                    | [log2timeline](https://github.com/log2timeline)                       |
+| [LazyOwn](https://github.com/grisuno/LazyOwn)                   | The first RedTeam/APT Framework with an AI-powered C&C, featuring rootkits to conceal campaigns, undetectable malleable implants | [Grisuno](https://github.com/grisuno)                                 |
+| [GAP SDK](https://github.com/GreenWaves-Technologies/gap_sdk)   | SDK for Greenwaves Technologies' GAP8 IoT Application Processor                                                                  | [GreenWaves Technologies](https://github.com/GreenWaves-Technologies) |
+| [REW Sploit](https://github.com/REW-sploit/REW-sploit)          | Emulate and Dissect Metasploit Framework (MSF) and other attacks                                                                 | [REW-sploit](https://github.com/REW-sploit)                           |
+| [tomcatmanager](https://github.com/tomcatmanager/tomcatmanager) | A command line tool and python library for managing a tomcat server                                                              | [tomcatmanager](https://github.com/tomcatmanager)                     |
+| [Falcon Toolkit](https://github.com/CrowdStrike/Falcon-Toolkit) | Unleash the power of the CrowdStrike Falcon Platform at the CLI                                                                  | [CrowdStrike](https://github.com/CrowdStrike)                         |
+| [EXPLIoT](https://gitlab.com/expliot_framework/expliot)         | Internet of Things Security Testing and Exploitation framework                                                                   | [expliot_framework](https://gitlab.com/expliot_framework/)            |
+| [Pobshell](https://github.com/pdalloz/pobshell)                 | A Bash‑like shell for live Python objects: `cd`, `ls`, `cat`, `find` and _CLI piping_ for object code, str values & more         | [Peter Dalloz](https://www.linkedin.com/in/pdalloz)                   |
 
 Possibly defunct but still good examples
 

{cmd2-4.0.0rc2 → cmd2-4.1.0}/README.md

@@ -26,7 +26,7 @@ of cmd to make your life easier and eliminates much of the boilerplate code whic
 when using cmd.
 
 > :warning: **If you are upgrading from an older version of `cmd2`, both `3.x` and `4.x` have some
-> significant backwards incompatibilities from version `2.x`. Please see the
+> significant backwards incompatibilities from previous versions. Please see the
 > [CHANGELOG](./CHANGELOG.md) for info on what has changed and the
 > [Migration Guide](https://cmd2.readthedocs.io/en/latest/upgrades/) for tips on upgrading from an
 > older version of `cmd2` to `4.x`**
@@ -154,23 +154,25 @@ reproduce the bug. At a minimum, please state the following:
 
 ## Projects using cmd2
 
-| Application Name                                                | Description                                                                                                                     | Organization or Author                                                |
-| --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
-| [CephFS Shell](https://github.com/ceph/ceph)                    | The Ceph File System, or CephFS, is a POSIX-compliant file system built on top of Ceph’s distributed object store               | [ceph](https://ceph.com/)                                             |
-| [garak](https://github.com/NVIDIA/garak)                        | LLM vulnerability scanner that checks if an LLM can be made to fail in a way we don't want                                      | [NVIDIA](https://github.com/NVIDIA)                                   |
-| [medusa](https://github.com/Ch0pin/medusa)                      | Binary instrumentation framework that that automates processes for the dynamic analysis of Android and iOS Applications         | [Ch0pin](https://github.com/Ch0pin)                                   |
-| [InternalBlue](https://github.com/seemoo-lab/internalblue)      | Bluetooth experimentation framework for Broadcom and Cypress chips                                                              | [Secure Mobile Networking Lab](https://github.com/seemoo-lab)         |
-| [SCCMHunter](https://github.com/garrettfoster13/sccmhunter)     | A post-ex tool built to streamline identifying, profiling, and attacking SCCM related assets in an Active Directory domain      | [Garret Foster](https://github.com/garrettfoster13)                   |
-| [Unipacker](https://github.com/unipacker/unipacker)             | Automatic and platform-independent unpacker for Windows binaries based on emulation                                             | [unipacker](https://github.com/unipacker)                             |
-| [Frankenstein](https://github.com/seemoo-lab/frankenstein)      | Broadcom and Cypress firmware emulation for fuzzing and further full-stack debugging                                            | [Secure Mobile Networking Lab](https://github.com/seemoo-lab)         |
-| [Poseidon](https://github.com/faucetsdn/poseidon)               | Leverages software-defined networks (SDNs) to acquire and then feed network traffic to a number of machine learning techniques. | [Faucet SDN](https://github.com/faucetsdn)                            |
-| [DFTimewolf](https://github.com/log2timeline/dftimewolf)        | A framework for orchestrating forensic collection, processing and data export                                                   | [log2timeline](https://github.com/log2timeline)                       |
-| [GAP SDK](https://github.com/GreenWaves-Technologies/gap_sdk)   | SDK for Greenwaves Technologies' GAP8 IoT Application Processor                                                                 | [GreenWaves Technologies](https://github.com/GreenWaves-Technologies) |
-| [REW Sploit](https://github.com/REW-sploit/REW-sploit)          | Emulate and Dissect Metasploit Framework (MSF) and other attacks                                                                | [REW-sploit](https://github.com/REW-sploit)                           |
-| [tomcatmanager](https://github.com/tomcatmanager/tomcatmanager) | A command line tool and python library for managing a tomcat server                                                             | [tomcatmanager](https://github.com/tomcatmanager)                     |
-| [Falcon Toolkit](https://github.com/CrowdStrike/Falcon-Toolkit) | Unleash the power of the CrowdStrike Falcon Platform at the CLI                                                                 | [CrowdStrike](https://github.com/CrowdStrike)                         |
-| [EXPLIoT](https://gitlab.com/expliot_framework/expliot)         | Internet of Things Security Testing and Exploitation framework                                                                  | [expliot_framework](https://gitlab.com/expliot_framework/)            |
-| [Pobshell](https://github.com/pdalloz/pobshell)                 | A Bash‑like shell for live Python objects: `cd`, `ls`, `cat`, `find` and _CLI piping_ for object code, str values & more        | [Peter Dalloz](https://www.linkedin.com/in/pdalloz)                   |
+| Application Name                                                | Description                                                                                                                      | Organization or Author                                                |
+| --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
+| [CephFS Shell](https://github.com/ceph/ceph)                    | The Ceph File System, or CephFS, is a POSIX-compliant file system built on top of Ceph’s distributed object store                | [ceph](https://ceph.com/)                                             |
+| [garak](https://github.com/NVIDIA/garak)                        | LLM vulnerability scanner that checks if an LLM can be made to fail in a way we don't want                                       | [NVIDIA](https://github.com/NVIDIA)                                   |
+| [Argus](https://github.com/jasonxtn/argus)                      | The Ultimate Information Gathering Toolkit                                                                                       | [JASON13](https://github.com/jasonxtn)                                |
+| [medusa](https://github.com/Ch0pin/medusa)                      | Binary instrumentation framework that that automates processes for the dynamic analysis of Android and iOS Applications          | [Ch0pin](https://github.com/Ch0pin)                                   |
+| [InternalBlue](https://github.com/seemoo-lab/internalblue)      | Bluetooth experimentation framework for Broadcom and Cypress chips                                                               | [Secure Mobile Networking Lab](https://github.com/seemoo-lab)         |
+| [SCCMHunter](https://github.com/garrettfoster13/sccmhunter)     | A post-ex tool built to streamline identifying, profiling, and attacking SCCM related assets in an Active Directory domain       | [Garret Foster](https://github.com/garrettfoster13)                   |
+| [Unipacker](https://github.com/unipacker/unipacker)             | Automatic and platform-independent unpacker for Windows binaries based on emulation                                              | [unipacker](https://github.com/unipacker)                             |
+| [Frankenstein](https://github.com/seemoo-lab/frankenstein)      | Broadcom and Cypress firmware emulation for fuzzing and further full-stack debugging                                             | [Secure Mobile Networking Lab](https://github.com/seemoo-lab)         |
+| [Poseidon](https://github.com/faucetsdn/poseidon)               | Leverages software-defined networks (SDNs) to acquire and then feed network traffic to a number of machine learning techniques.  | [Faucet SDN](https://github.com/faucetsdn)                            |
+| [DFTimewolf](https://github.com/log2timeline/dftimewolf)        | A framework for orchestrating forensic collection, processing and data export                                                    | [log2timeline](https://github.com/log2timeline)                       |
+| [LazyOwn](https://github.com/grisuno/LazyOwn)                   | The first RedTeam/APT Framework with an AI-powered C&C, featuring rootkits to conceal campaigns, undetectable malleable implants | [Grisuno](https://github.com/grisuno)                                 |
+| [GAP SDK](https://github.com/GreenWaves-Technologies/gap_sdk)   | SDK for Greenwaves Technologies' GAP8 IoT Application Processor                                                                  | [GreenWaves Technologies](https://github.com/GreenWaves-Technologies) |
+| [REW Sploit](https://github.com/REW-sploit/REW-sploit)          | Emulate and Dissect Metasploit Framework (MSF) and other attacks                                                                 | [REW-sploit](https://github.com/REW-sploit)                           |
+| [tomcatmanager](https://github.com/tomcatmanager/tomcatmanager) | A command line tool and python library for managing a tomcat server                                                              | [tomcatmanager](https://github.com/tomcatmanager)                     |
+| [Falcon Toolkit](https://github.com/CrowdStrike/Falcon-Toolkit) | Unleash the power of the CrowdStrike Falcon Platform at the CLI                                                                  | [CrowdStrike](https://github.com/CrowdStrike)                         |
+| [EXPLIoT](https://gitlab.com/expliot_framework/expliot)         | Internet of Things Security Testing and Exploitation framework                                                                   | [expliot_framework](https://gitlab.com/expliot_framework/)            |
+| [Pobshell](https://github.com/pdalloz/pobshell)                 | A Bash‑like shell for live Python objects: `cd`, `ls`, `cat`, `find` and _CLI piping_ for object code, str values & more         | [Peter Dalloz](https://www.linkedin.com/in/pdalloz)                   |
 
 Possibly defunct but still good examples
 

{cmd2-4.0.0rc2 → cmd2-4.1.0}/cmd2/__init__.py

@@ -11,7 +11,10 @@ from . import (
     rich_utils,
     string_utils,
 )
-from .annotated import with_annotated
+from .annotated import (
+    ArgumentBlock,
+    with_annotated,
+)
 from .argparse_completer import set_default_argparse_completer
 from .argparse_utils import (
     Cmd2ArgumentParser,
@@ -88,6 +91,8 @@ __all__: list[str] = [  # noqa: RUF022
     "Choices",
     "CompletionItem",
     "Completions",
+    # Annotated commands
+    "ArgumentBlock",
     # Decorators
     "with_annotated",
     "with_argument_list",