Merge branch 'main' into ap_command_spec

Author: kmvanbrunt

.github/workflows/codeql-analysis.yml

@@ -32,7 +32,7 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v6.0.2
+        uses: actions/checkout@v6.0.3
         with:
           # We must fetch at least the immediate parents so that if this is
           # a pull request then we can checkout the head.

.github/workflows/docs.yml

@@ -17,7 +17,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Check out
-        uses: actions/checkout@v6.0.2
+        uses: actions/checkout@v6.0.3
         with:
           fetch-depth: 0 # Needed for setuptools_scm to work correctly
 

.github/workflows/quality.yml

@@ -15,7 +15,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Check out
-        uses: actions/checkout@v6.0.2
+        uses: actions/checkout@v6.0.3
         with:
           fetch-depth: 0 # Needed for setuptools_scm to work correctly
 

.github/workflows/tests.yml

@@ -21,7 +21,7 @@ jobs:
         shell: bash
     steps:
       - name: Check out
-        uses: actions/checkout@v6.0.2
+        uses: actions/checkout@v6.0.3
         with:
           fetch-depth: 0 # Needed for setuptools_scm to work correctly
       - name: Install uv

.github/workflows/typecheck.yml

@@ -22,7 +22,7 @@ jobs:
         shell: bash
     steps:
       - name: Check out
-        uses: actions/checkout@v6.0.2
+        uses: actions/checkout@v6.0.3
         with:
           fetch-depth: 0 # Needed for setuptools_scm to work correctly
 

.pre-commit-config.yaml

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

CHANGELOG.md

@@ -1,4 +1,4 @@
-## 4.0.0 (TBD 2026)
+## 4.0.0 (June TBD, 2026)
 
 ### Summary
 
@@ -171,6 +171,16 @@ prompt is displayed.
       is enabled.
     - `alias` and `macro` subcommands for `create` and `delete` now output their non-essential
       success case output using `pfeedback`
+- Experimental features
+    - New `@with_annotated` decorator, a type-hint-driven alternative to `@with_argparse` that
+      builds the parser automatically from a command's signature (positional/option inference,
+      enum/literal/path/collection handling, subcommands, groups, mutex). See the
+      [annotated_example.py](https://github.com/python-cmd2/cmd2/blob/main/examples/annotated_example.py)
+      example for demonstration of usage.
+        - This feature allows declaring `cmd2` command parameters using type hints using syntax
+          essentially identical to that used by [Typer](https://typer.tiangolo.com/)
+        - You use declarative syntax to define the arguments a command takes and the
+          `@with_annotated` decorator builds an `argparse` parser for you
 
 ## 3.5.1 (April 24, 2026)
 

cmd2/__init__.py

@@ -11,6 +11,7 @@
     rich_utils,
     string_utils,
 )
+from .annotated import with_annotated
 from .argparse_completer import set_default_ap_completer_type
 from .argparse_utils import (
     Cmd2ArgumentParser,
@@ -88,6 +89,7 @@
     "CompletionItem",
     "Completions",
     # Decorators
+    "with_annotated",
     "with_argument_list",
     "with_argparser",
     "with_category",

cmd2/annotated.py

@@ -16,10 +16,10 @@
 Example::
 
     # -f argument expects at least 3 values
-    parser.add_argument('-f', nargs=(3,))
+    parser.add_argument("-f", nargs=(3,))
 
     # -f argument expects 3 to 5 values
-    parser.add_argument('-f', nargs=(3, 5))
+    parser.add_argument("-f", nargs=(3, 5))
 
 
 **Completion**
@@ -38,8 +38,8 @@
 
     Example::
 
-        my_list = ['An Option', 'SomeOtherOption']
-        parser.add_argument('-o', '--options', choices=my_list)
+        my_list = ["An Option", "SomeOtherOption"]
+        parser.add_argument("-o", "--options", choices=my_list)
 
 ``choices_provider`` - pass a function that returns a Choices object. This is good in
 cases where the choices are dynamically generated when the user hits tab.
@@ -50,6 +50,7 @@ def my_choices_provider(self) -> Choices:
             ...
             return my_choices
 
+
         parser.add_argument("arg", choices_provider=my_choices_provider)
 
 ``completer`` - pass a function that does custom completion and returns a Completions object.
@@ -60,17 +61,16 @@ def my_choices_provider(self) -> Choices:
     Example::
 
         # This adds file-path completion to an argument
-        parser.add_argument('-o', '--options', completer=cmd2.Cmd.path_complete)
+        parser.add_argument("-o", "--options", completer=cmd2.Cmd.path_complete)
 
     You can use functools.partial() to prepopulate values of the underlying
     choices and completer functions/methods.
 
     Example::
 
         # This says to call path_complete with a preset value for its path_filter argument
-        dir_completer = functools.partial(path_complete,
-                                          path_filter=lambda path: os.path.isdir(path))
-        parser.add_argument('-o', '--options', completer=dir_completer)
+        dir_completer = functools.partial(path_complete, path_filter=lambda path: os.path.isdir(path))
+        parser.add_argument("-o", "--options", completer=dir_completer)
 
 For ``choices_provider`` and ``completer``, do not set them to a bound method. This
 is because ArgparseCompleter passes the `self` argument explicitly to these