Template functionality for argument blocks using `with_annotaed` decorator

[neoniobium]

Feature Request

To avoid redundant code, add a template mechanism for argument blocks that appear in multiple commands. Using the with_argparse decorator this is easy by reusing a function that modifies a parser; with_annotated currently has no simple equivalent.

Possible solutions

• Use a TypedDict + Unpack to reuse a named block of annotations:

class ArgumentBlock(TypedDict):
    # define reusable keys/values here
    ...

class App(Cmd):

    @with_annotated
    def do_a(..., **kwargs: Unpack[ArgumentBlock]) -> None:
        ...

    @with_annotated
    def do_b(..., **kwargs: Unpack[ArgumentBlock]) -> None:
        ...

• Allow attaching a predefined parser to the parser generated by with_annotated, and expose the resulting namespace inside the decorated method for easy access.

Both approaches reduce duplication; the second may be simpler to implement.

[KelvinChung2000]

I prefer the TypedDict approach. I am considering a "template dataclass". So the use case becomes:

@dataclass
class ArgumentBlock():
    # define reusable keys/values here
    ...

class App(Cmd):

    @with_annotated
    def do_a(..., arg_block: ArgumentBlock) -> None:
        ...

    @with_annotated
    def do_b(..., arg_block: Annotated[ArgumentBlock, Template]) -> None:
        ...

And the type resolution is checking for a dataclass type. It will likely need some extra constraints, such as being used only on the last argument or requiring something like the second example. This depends on what can go wrong.

[neoniobium]

Looks reasonable to me. I think your approach is better than simply using **kwargs: this also lets a user use multiple different argument blocks in the same method without merging them. I think this allows for a very clean design.

[tleonhardt]

@KelvinChung2000 I'm thinking about putting out a release over the weekend. Would you like to address this or the other open issue prior to putting out the next release?

[KelvinChung2000]

I have the feature mostly implemented. I will open the PR soon. It will address this and #1690, since this block feature provides a nice way to support typed args with parent argument inheritance.