Shared options / custom help text for every subcommand

[pawamoy]

To customize the description of the --help flag for each of my subcommand, I used this pattern:

from dataclasses import dataclass
from typing import Annotated

import cappa


@dataclass(kw_only=True)
class HelpOption:
    help: Annotated[
        bool,
        cappa.Arg(
            short="-h",
            long=True,
            action=cappa.ArgAction.help,
            num_args=0,
            help="Print the program help and exit.",
        ),
    ] = False


@cappa.command(name="a")
@dataclass(kw_only=True)
class CommandA(HelpOption):
    ...


@cappa.command(name="b")
@dataclass(kw_only=True)
class CommandB(HelpOption):
    ...

Decorating commands with dataclass is necessary, because otherwise the base class (HelpOption) does nothing through inheritance, and by the time @cappa.command picks it up it's too late.

The kw_only=True option is also necessary, because the order of attributes matter in a dataclass, and attributes without a default value cannot appear after attributes with a default value, unless they're all keyword-only attributes.

This pattern can be used more generally to share options between commands. Here I'm just using it to customize the description of --help once for all subcommands.

[DanCardin]

For what it's worth, help specifically, using the help= arg, should apply to all child subcommands. So I wouldn't expect you to need to resort to this for help. I mostly only point this out in case there's some deficiency where that is not giving you the behavior. you want?

With that said, this pattern certainly makes sense generally.

[pawamoy]

Yeah I was initially going to open a bug report, so that help applies to all subcommands, but I actually prefer declaring it explicitly in the dataclass, so I don't mind if it stays as it is. Also, argparse has the same UX (you need to customize the help message on every subparser), so it's not surprising behavior.

[DanCardin]

i'll have to go write a test to check, but im reasonably certain the internal add_meta_actions impl uses the literal help arg you hand invoke/parse/collect, so it should propagate downward into all the subcommands

And (fwiw) i designed it outside the dataclass because for any instance of that class, it's always going to be false (or None for completion) given the behavior of the action. Which is why I personally prefer it off the actual object definition