Typing of optional subcommand

[pawamoy]

Just a tiny un-intuitive thing. If I specify an optional subcommand like that:

    subcommand: Annotated[
        cappa.Subcommands[Subcommand1 | Subcommand2] | None,
    ] = None

...trying to call the parent command (prog command in this example) results in:

% prog command
prog: error: Invalid value for 'subcommand': Possible variants
 - Union[Subcommand1, Subcommand2]: Possible variants
 - Subcommand1: Subcommand1.__init__() takes 1 positional argument but 2 were given
 - Subcommand2: Subcommand2.__init__() takes 1 positional argument but 2 were given
 - <no value>

(I'm using Annotate to add a PEP 727 Doc("...") string to the subcommand.)

The correct way to annotate the subcommand is to put None inside Subcommands:

    subcommand: Annotated[
        cappa.Subcommands[Subcommand1 | Subcommand2 | None],
    ] = None

...which makes sense, since Subcommands is:

Subcommands: TypeAlias = Annotated[T, Subcommand]

...and seems to make type-checkers happy anyway. I simply had to go back through comments I posted here to find out I had to put None inside Subcommands ☺️

If there's an easy "fix" to support None outside of Subcommands, great, if not, just ignore this! Or maybe a quick note in the docs is more than enough, like a small "Optional subcommand" paragraph here: https://cappa.readthedocs.io/en/latest/annotation.html#subcommands.

[pawamoy]

As seen in #163, we can actually annotate the subcommand like this:

    subcommand: Annotated[
        Subcommand1 | Subcommand2 | None,
        cappa.Subcommand(),
    ] = None

...making this intuitive again 🙂

[DanCardin]

I created #165, in case it's doable to reliably flatten annotateds, but the above is still probably the right "answer"