cmd2 4.1.2__tar.gz → 4.2.1__tar.gz

{cmd2-4.1.2 → cmd2-4.2.1}/.pre-commit-config.yaml

@@ -14,7 +14,7 @@ repos:
       - id: trailing-whitespace
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: "v0.15.21"
+    rev: "v0.16.3"
     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.48.0
+    rev: v1.49.0
     hooks:
       - id: typos
         exclude: |

{cmd2-4.1.2 → cmd2-4.2.1}/CHANGELOG.md

@@ -1,3 +1,41 @@
+## 4.2.1 (August 22, 2026)
+
+- Enhancements
+    - Added bracketed paste support so multiple pasted commands execute sequentially and multiline
+      commands continue as expected.
+
+- Bug Fixes
+    - Enabled Ctrl-Z suspension at the prompt
+
+## 4.2.0 (August 6, 2026)
+
+- Enhancements
+    - `@with_annotated` argument groups can now contain an `ArgumentBlock`'s arguments. A `Group`
+      member names a command-line argument, and a block expands into one argument per field, so its
+      fields are named: `Group("host", "port")`.
+- Breaking Changes
+    - A `Group` member now names an argument rather than a parameter. The two differ only for an
+      `ArgumentBlock` parameter, which is expanded away and has no argument of its own:
+      `Group("conn")` now raises `ValueError` pointing at the block's fields. It previously produced
+      an empty argument group in `groups=` and a `KeyError` in `mutually_exclusive_groups=`.
+    - Whether a `Group` member exists is now validated when the parser is built rather than at
+      decoration time, because a block's field names cannot be known without resolving its type
+      hint, and resolving hints eagerly would break forward-referenced annotations. A typo in a
+      member name still raises `ValueError`, but on first use of that command rather than at class
+      definition. The spec-shape rules (a member listed twice, a member in two groups,
+      `required=True` on a plain group, the mutex nesting rules) are unaffected and still hard-fail
+      at decoration time.
+- Bug Fixes
+    - Fixed `@with_annotated(base_command=True)` not listing its subcommands under the positional
+      arguments section of the parent command's `--help`, unlike `argparse` and
+      `Cmd2ArgumentParser`. They were placed in an untitled section of their own instead. Passing
+      `subcommand_title` or `subcommand_description` still gives the subcommands a dedicated section
+      ([#1715](https://github.com/python-cmd2/cmd2/issues/1715)).
+    - Fix `@with_annotated` decorator so using `ArgumentBlock` works with groups
+      ([#1718](https://github.com/python-cmd2/cmd2/issues/1718)).
+    - Fixed bug where already sorted `choices_provider` results were being re-sorted
+      ([#1727](https://github.com/python-cmd2/cmd2/issues/1727)).
+
 ## 4.1.2 (July 16, 2026)
 
 - Enhancements

{cmd2-4.1.2 → cmd2-4.2.1}/Makefile

@@ -18,8 +18,8 @@ check: ## Run code quality tools.
 	@uv lock --locked
 	@echo "🚀 Auto-formatting/Linting code and documentation: Running prek"
 	@uv run prek run -a
-	@echo "🚀 Static type checking: Running mypy"
-	@uv run mypy
+	@echo "🚀 Static type checking: Running ty"
+	@uv run ty check
 
 .PHONY: format
 format: ## Perform ruff formatting
@@ -31,7 +31,7 @@ lint: ## Perform ruff linting
 
 .PHONY: typecheck
 typecheck: ## Perform type checking
-	@uv run mypy
+	@uv run ty check
 
 .PHONY: test
 test: ## Test the code with pytest.
@@ -76,7 +76,7 @@ publish: validate-tag build ## Publish a release to PyPI, uses token from ~/.pyp
 # Define variables for files/directories to clean
 BUILD_DIRS = build dist *.egg-info
 DOC_DIRS = build
-MYPY_DIRS = .mypy_cache dmypy.json dmypy.sock
+TY_DIRS = .ty_cache .red_knot_cache
 TEST_DIRS = .cache .pytest_cache htmlcov
 TEST_FILES = .coverage coverage.xml
 
@@ -90,10 +90,10 @@ 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-ty
+clean-ty: ## Clean ty artifacts
+	@echo "🚀 Removing ty artifacts"
+	@uv run python -c "import shutil; import os; [shutil.rmtree(d, ignore_errors=True) for d in '$(TY_DIRS)'.split() if os.path.isdir(d)]"
 
 .PHONY: clean-pycache
 clean-pycache: ## Clean pycache artifacts
@@ -112,7 +112,7 @@ clean-test: ## Clean test artifacts
 	@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
+clean: clean-build clean-docs clean-ty clean-pycache clean-ruff clean-test ## Clean all artifacts
 	@echo "🚀 Cleaned all artifacts"
 
 .PHONY: help

{cmd2-4.1.2 → cmd2-4.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cmd2
-Version: 4.1.2
+Version: 4.2.1
 Summary: cmd2 - quickly build feature-rich and user-friendly interactive command line applications in Python
 Author: cmd2 Contributors
 License-Expression: MIT
@@ -21,7 +21,7 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: prompt-toolkit>=3.0.52
+Requires-Dist: prompt-toolkit>=3.0.53
 Requires-Dist: pyperclip>=1.8.2
 Requires-Dist: rich>=15.0.0
 Requires-Dist: rich-argparse>=1.7.2

{cmd2-4.1.2 → cmd2-4.2.1}/cmd2/annotated.py

@@ -175,9 +175,11 @@ dataclass constructor at reconstruction time, so a ``default_factory`` yields a
 argument.  A field whose type is itself a block is not expanded (no recursion) and raises the
 unsupported-type error.  Because fields expand flat, every field name must be unique across the command's
 own parameters and every other block's fields -- a collision (which would put two argparse actions on one
-namespace dest) raises ``TypeError`` when the parser is built.  Block fields cannot participate in
-``groups=`` / ``mutually_exclusive_groups=`` (those reference the function's own parameter names, which are
-validated without resolving type hints).  A block must be the *bare* annotation of a regular parameter:
+namespace dest) raises ``TypeError`` when the parser is built.  Block fields can participate in
+``groups=`` / ``mutually_exclusive_groups=``: a group names arguments, and because a block expands to one
+argument per field, you name its *field* names.  Since resolving those field names needs the block's
+type hints, this membership is checked when the parser is built rather than at decoration time.  A block
+must be the *bare* annotation of a regular parameter:
 wrapping it in ``Annotated``/``Optional``/a union, or using it as ``*args`` / ``**kwargs``, raises
 ``TypeError`` (to use a dataclass as a single value instead, make it a plain ``@dataclass`` with an
 ``Argument(converter=...)``).  An ``ArgumentBlock`` subclass that is not a ``@dataclass`` has no fields and
@@ -414,7 +416,7 @@ class _BaseArgMetadata:
         """
         reserved = self._RESERVED_EXTRA_KWARGS & extra_kwargs.keys()
         if reserved:
-            name = sorted(reserved)[0]
+            name = min(reserved)
             # Per-key remediation hint for the reserved kwarg.
             hint = {
                 "type": (
@@ -552,25 +554,20 @@ class Group:
     ) -> None:
         """Initialise an argument group definition.
 
-        :param members: parameter names to place in the group (at least one)
+        :param members: argument names to place in the group (at least one).  A plain parameter's name is its
+                        argument name; for an ``ArgumentBlock`` name its fields.
         :param title: group title shown as a help section header
         :param description: group description shown under the title
         :param required: ``mutually_exclusive_groups`` only -- require exactly one member.
                          On a ``groups=`` entry it raises ``ValueError``.
         """
         if not members:
-            raise ValueError("Group requires at least one member parameter name")
+            raise ValueError("Group requires at least one member argument name")
         self.members = members
         self.title = title
         self.description = description
         self.required = required
 
-    def _validate_members(self, *, all_param_names: set[str], group_type: str) -> None:
-        """Validate that every referenced member parameter exists."""
-        for name in self.members:
-            if name not in all_param_names:
-                raise ValueError(f"{group_type} references nonexistent parameter {name!r}")
-
 
 #: Metadata extracted from ``Annotated[T, meta]``, or ``None`` for plain types.
 ArgMetadata = Argument | Option | None
@@ -711,10 +708,10 @@ class _CollectionCastingAction(argparse._StoreAction):
 
     def __call__(
         self,
-        _parser: argparse.ArgumentParser,
+        parser: argparse.ArgumentParser,  # noqa: ARG002
         namespace: argparse.Namespace,
         values: Any,
-        _option_string: str | None = None,
+        option_string: str | None = None,  # noqa: ARG002
     ) -> None:
         result = values
         if self._container_factory is not None and isinstance(values, list):
@@ -882,7 +879,7 @@ def _resolve_union(
         raise TypeError(f"Union type {type_names} is ambiguous for auto-resolution.")
 
     parts = [_resolve_base_type(member, allow_unknown_entry=allow_unknown_entry) for member in non_none]
-    # Every part is an Enum (guarded above), so each has a converter; the None-filter keeps mypy happy.
+    # Every part is an Enum (guarded above), so each has a converter; the None-filter keeps the type checker happy.
     converters = [part.converter for part in parts if part.converter is not None]
     choices = _dedupe_choices(choice for part in parts for choice in (part.choices or []))
 
@@ -2072,6 +2069,39 @@ def _shared_field_dest(dc_type: type, field_name: str) -> str:
     return constants.cmd2_private_attr_name(f"shared_{id(dc_type):x}_{field_name}")
 
 
+def _check_group_members_exist(
+    by_name: dict[str, _ArgparseArgument],
+    block_param_names: set[str],
+    func_qualname: str,
+    *specs: tuple[Group, ...] | None,
+) -> None:
+    """Reject a ``Group`` member that names no command-line argument, once every argument is built.
+
+    :func:`_validate_group_specs` cannot do this at decoration time: an ArgumentBlock's arguments are its
+    dataclass fields, which only resolving the block's type hint would reveal, and resolving hints there
+    would break forward-referenced annotations.  So this is where a bad member name is finally caught.
+
+    Naming the block parameter itself is the likely mistake -- it reads natural but the parameter is expanded
+    away and has no argument -- so it gets its own message pointing at the fields to name instead.
+    """
+    for spec_group in specs:
+        for spec in spec_group or ():
+            for name in spec.members:
+                if name in by_name:
+                    continue
+                if name in block_param_names:
+                    raise ValueError(
+                        f"group in {func_qualname} references {name!r}, which is an ArgumentBlock parameter "
+                        f"and not a command-line argument: a block is expanded into one argument per field, "
+                        f"so name those fields instead."
+                    )
+                raise ValueError(
+                    f"group in {func_qualname} references {name!r}, which is not a command-line argument. "
+                    f"Members name arguments: a plain parameter is its own argument, and an ArgumentBlock's "
+                    f"arguments are its field names."
+                )
+
+
 def _link_mutex_group_membership(
     by_name: dict[str, _ArgparseArgument],
     mutually_exclusive_groups: tuple[Group, ...] | None,
@@ -2079,8 +2109,7 @@ def _link_mutex_group_membership(
     """Append each mutex group's 1-based index to its member arguments' ``mutex_group_indices``.
 
     This membership is the fact behind the required-member constraint row.  Member references are
-    validated upstream by :func:`_validate_group_specs` before this runs, so every member name
-    resolves to a built argument.
+    resolved to built arguments upstream by :func:`_check_group_members_exist` before this runs.
     """
     if not mutually_exclusive_groups:
         return
@@ -2160,7 +2189,7 @@ def _find_argument_block(hint: Any) -> type[ArgumentBlock] | None:
     return None
 
 
-def _init_field_names(dc_type: type) -> list[str]:
+def _init_field_names(dc_type: Any) -> list[str]:
     """Names of a dataclass's ``init`` fields in definition order (the flat argument names of a block)."""
     return [f.name for f in fields(dc_type) if f.init]
 
@@ -2352,6 +2381,7 @@ def _resolve_parameters(
     *,
     skip_params: frozenset[str] = _SKIP_PARAMS,
     base_command: bool = False,
+    groups: tuple[Group, ...] | None = None,
     mutually_exclusive_groups: tuple[Group, ...] | None = None,
 ) -> tuple[list[_ArgparseArgument], set[type]]:
     """Resolve a function signature into argparse-argument builders and inheritable-block types.
@@ -2378,6 +2408,7 @@ def _resolve_parameters(
     resolved: list[_ArgparseArgument] = []
     inherited_field_names: set[str] = set()
     base_args_types: set[type] = set()
+    block_param_names: set[str] = set()
 
     # Skip the first parameter by position (self/cls for methods)
     params = list(sig.parameters.items())
@@ -2398,6 +2429,7 @@ def _resolve_parameters(
                     f"cannot have a default value; remove the default."
                 )
             inherited_field_names.update(_init_field_names(inherited))
+            block_param_names.add(name)
             continue
 
         # An ArgumentBlock-typed parameter is an argument block: expand its fields in place (flat) instead of
@@ -2416,6 +2448,7 @@ def _resolve_parameters(
                 block_hint, func_qualname=func.__qualname__, base_command=base_command, shared=name == NS_ATTR_BASE_ARGS
             )
             _reject_field_shadowing_block_param(block_hint, name, func.__qualname__)
+            block_param_names.add(name)
             resolved.extend(expanded)
             continue
         # The magic name requires a bare ArgumentBlock; a non-block annotation on it is a clear mistake.
@@ -2480,6 +2513,7 @@ def _resolve_parameters(
     for arg in positionals[:-1]:  # every positional except the last has a following positional
         arg.has_following_positional = True
     by_name = {arg.name: arg for arg in resolved}
+    _check_group_members_exist(by_name, block_param_names, func.__qualname__, groups, mutually_exclusive_groups)
     _link_mutex_group_membership(by_name, mutually_exclusive_groups)
     for arg in resolved:
         arg._check_constraints()
@@ -2539,30 +2573,22 @@ def _filtered_namespace_kwargs(
 
 
 def _validate_group_specs(
-    func: Callable[..., Any],
-    *,
-    skip_params: frozenset[str],
     groups: tuple[Group, ...] | None,
     mutually_exclusive_groups: tuple[Group, ...] | None,
 ) -> None:
-    """Validate ``groups=`` / ``mutually_exclusive_groups=`` specs from parameter names alone.
-
-    Runs at decoration time (from both the regular-command and subcommand decoration paths, and
-    again from :func:`build_parser_from_function` for direct callers), so a misconfigured group
-    hard-fails when the class is defined instead of on first command use, where cmd2's runtime
-    handler turns the error into a printed message.  Reads only parameter names and the ``Group``
-    specs -- never the type hints -- so forward-referenced annotations still decorate.  The one
-    group rule that needs the annotations (a required member in a mutually exclusive group) stays
-    in :data:`_CONSTRAINTS` and fires when the parser is built.
+    """Validate the *shape* of ``groups=`` / ``mutually_exclusive_groups=`` specs.
+
+    Runs at decoration time (from both the regular-command and subcommand decoration paths, and again from
+    :func:`build_parser_from_function` for direct callers), so a misshapen group hard-fails when the class is
+    defined instead of on first command use, where cmd2's runtime handler turns the error into a printed
+    message.  Reads only the ``Group`` specs -- never the signature or the type hints -- so
+    forward-referenced annotations still decorate.
     """
     if not groups and not mutually_exclusive_groups:
         return
-    params = list(inspect.signature(func).parameters)[1:]  # skip self/cls by position
-    all_param_names = {name for name in params if name not in skip_params}
 
     group_entry_for: dict[str, int] = {}
     for index, spec in enumerate(groups or (), start=1):
-        spec._validate_members(all_param_names=all_param_names, group_type="groups")
         if spec.required:
             raise ValueError(
                 "Group(required=True) is only valid in mutually_exclusive_groups; "
@@ -2580,7 +2606,6 @@ def _validate_group_specs(
 
     mutex_entry_for: dict[str, int] = {}
     for index, spec in enumerate(mutually_exclusive_groups or (), start=1):
-        spec._validate_members(all_param_names=all_param_names, group_type="mutually_exclusive_groups")
         for name in spec.members:
             previous = mutex_entry_for.get(name)
             if previous == index:
@@ -2721,7 +2746,7 @@ def build_parser_from_function(
     from . import argparse_utils
 
     # The decorator already ran this at decoration time; direct callers get the same checks here.
-    _validate_group_specs(func, skip_params=skip_params, groups=groups, mutually_exclusive_groups=mutually_exclusive_groups)
+    _validate_group_specs(groups, mutually_exclusive_groups)
 
     parser_cls = parser_class or argparse_utils.DEFAULT_ARGUMENT_PARSER
     if "description" not in parser_kwargs:
@@ -2735,6 +2760,7 @@ def build_parser_from_function(
     resolved, base_args_types = _resolve_parameters(
         func,
         skip_params=skip_params,
+        groups=groups,
         mutually_exclusive_groups=mutually_exclusive_groups,
     )
 
@@ -2827,15 +2853,17 @@ def _make_parser_builder(
             **options.parser_kwargs,
         )
         if base_command:
-            # dict[str, Any] is load-bearing: the typeshed stub types title/metavar as non-None,
-            # but argparse accepts None at runtime, so splatting avoids a false overload error.
+            # dict[str, Any] is load-bearing: title/description are added conditionally below,
+            # which the typeshed overloads for add_subparsers cannot express.
             kwargs: dict[str, Any] = {
                 "dest": "subcommand",
                 "metavar": options.subcommand_metavar,
                 "required": options.subcommand_required,
-                "title": options.subcommand_title,
-                "description": options.subcommand_description,
             }
+            if options.subcommand_title is not None:
+                kwargs["title"] = options.subcommand_title
+            if options.subcommand_description is not None:
+                kwargs["description"] = options.subcommand_description
             parser.add_subparsers(**kwargs)
         return parser
 
@@ -2862,12 +2890,7 @@ def _build_subcommand_handler(
     # Validate the group specs eagerly (decoration time) so a misconfigured group hard-fails when
     # the class is defined; the name-only checks never resolve type hints, so forward-referenced
     # annotations still decorate and the parser build stays deferred.
-    _validate_group_specs(
-        func,
-        skip_params=_SKIP_PARAMS,
-        groups=options.groups,
-        mutually_exclusive_groups=options.mutually_exclusive_groups,
-    )
+    _validate_group_specs(options.groups, options.mutually_exclusive_groups)
     if base_command:
         # Validate eagerly (decoration time); the base-command rows in _CONSTRAINTS fire here.
         # skip_params is spelled out so this call cannot silently diverge from the parser build below.
@@ -3051,12 +3074,7 @@ def with_annotated(
         # Validate the group specs eagerly (decoration time) so a misconfigured group hard-fails when
         # the class is defined; the name-only checks never resolve type hints, so forward-referenced
         # annotations still decorate and the parser build stays deferred.
-        _validate_group_specs(
-            fn,
-            skip_params=skip_params,
-            groups=options.groups,
-            mutually_exclusive_groups=options.mutually_exclusive_groups,
-        )
+        _validate_group_specs(options.groups, options.mutually_exclusive_groups)
         if base_command:
             # Validate eagerly (decoration time); the base-command rows in _CONSTRAINTS fire here.
             _resolve_parameters(fn, skip_params=skip_params, base_command=True)
@@ -3095,6 +3113,9 @@ def with_annotated(
             except SystemExit as exc:
                 raise Cmd2ArgparseError from exc
 
+            if ns is None:
+                raise ValueError("ns is None")
+
             setattr(ns, constants.NS_ATTR_STATEMENT, statement)
             handler = getattr(ns, constants.NS_ATTR_SUBCOMMAND_FUNC, None)
             if base_command and handler is not None:

{cmd2-4.1.2 → cmd2-4.2.1}/cmd2/argparse_completer.py

@@ -694,7 +694,7 @@ class ArgparseCompleter:
         self._parser.print_help(file)
 
     def _choices_to_items(self, arg_state: _ArgumentState) -> list[CompletionItem]:
-        """Convert choices from action to list of CompletionItems."""
+        """Convert an action's choices to a list of CompletionItems."""
         if arg_state.action.choices is None:
             return []
 
@@ -785,13 +785,15 @@ class ArgparseCompleter:
                     cmd_set,
                 )
                 all_choices = list(choices_provider(*args, **kwargs))
+                sort = False  # choices_provider results are already sorted, so don't re-sort them
             else:
                 all_choices = self._choices_to_items(arg_state)
+                sort = True
 
             # Filter used values and run basic completion
             used_values = consumed_arg_values.get(arg_state.action.dest, [])
             filtered = [choice for choice in all_choices if choice.text not in used_values]
-            completions = self._cmd_app.basic_complete(text, line, begidx, endidx, filtered)
+            completions = self._cmd_app.basic_complete(text, line, begidx, endidx, filtered, sort=sort)
 
         return self._build_completion_table(arg_state, completions)
 

{cmd2-4.1.2 → cmd2-4.2.1}/cmd2/argparse_utils.py

@@ -747,8 +747,8 @@ class Cmd2ArgumentParser(argparse.ArgumentParser):
         super().__init__(
             prog=prog,
             usage=usage,
-            description=description,  # type: ignore[arg-type]
-            epilog=epilog,  # type: ignore[arg-type]
+            description=description,  # type: ignore[arg-type, ty:invalid-argument-type]
+            epilog=epilog,  # type: ignore[arg-type, ty:invalid-argument-type]
             parents=parents,
             formatter_class=formatter_class,
             prefix_chars=prefix_chars,
@@ -772,7 +772,7 @@ class Cmd2ArgumentParser(argparse.ArgumentParser):
         self.description: HelpContent | None  # type: ignore[assignment]
         self.epilog: HelpContent | None  # type: ignore[assignment]
 
-    def print_usage(self, file: IO[str] | None = None) -> None:  # type:ignore[override]
+    def print_usage(self, file: IO[str] | None = None) -> None:  # type: ignore[override, ty:invalid-method-override]
         """Override to ensure the formatter is aware of the target file."""
         if file is None:
             file = self._thread_locals.current_output_file
@@ -780,7 +780,7 @@ class Cmd2ArgumentParser(argparse.ArgumentParser):
         with self.output_to(file):
             super().print_usage(file)
 
-    def print_help(self, file: IO[str] | None = None) -> None:  # type:ignore[override]
+    def print_help(self, file: IO[str] | None = None) -> None:  # type: ignore[override, ty:invalid-method-override]
         """Override to ensure the formatter is aware of the target file."""
         if file is None:
             file = self._thread_locals.current_output_file
@@ -831,7 +831,7 @@ class Cmd2ArgumentParser(argparse.ArgumentParser):
         temp_parser = Cmd2ArgumentParser(
             prog=self.prog,
             usage=None,
-            formatter_class=self.formatter_class,
+            formatter_class=cast(type[Cmd2HelpFormatter], self.formatter_class),
             add_help=False,
         )
 
@@ -1037,7 +1037,8 @@ class Cmd2ArgumentParser(argparse.ArgumentParser):
 
     def _get_formatter(self, *_args: Any, **_kwargs: Any) -> Cmd2HelpFormatter:
         """Override with customizations for Cmd2HelpFormatter."""
-        return self.formatter_class(prog=self.prog, file=self._thread_locals.current_output_file)
+        formatter_class = cast(type[Cmd2HelpFormatter], self.formatter_class)
+        return formatter_class(prog=self.prog, file=self._thread_locals.current_output_file)
 
     def format_help(self, *args: Any, **kwargs: Any) -> str:
         """Override to add a newline."""