feat: Implement exclusive groups.

[DanCardin]

arg: Annotated[
    int,
    cappa.Arg(short="-v", action=cappa.ArgAction.count),
    cappa.Arg(long="--verbosity"),
] = 0

Is the proposed syntax for this so far. This might be nicer as X | Y, but that gets somewhat more magical implementation wise and it's not entirely clear that it's that much better, if at all.

---

What's unclear is whether this syntax is useful without also implying mutual exclusivity. I could imagine for an int target, --verbosity 3 -v might yield arg == 4. but ordering would become significant and most other types of inputs wouldn't make sense.

...granted this is essentially exactly how all of argparse's arguments work (unless there's validation i'm forgetting), relying on you to select metavars that dont conflict in stupid ways...

Ultimately, you'd still be able to opt out of the default behavior by explicitly setting exclusive_group=None, for whatever that's worth soooooo 🤷

[DanCardin]

In fact, it's significantly more difficult and ambiguous when allowing Annotated[int, Arg()] | Annotated[str, Arg()]. Namely, because parsing of values into their resultant types happens after parsing has completed, by which point it's too late to keep track of whether the int variant was selected or not.

And mapping happens after parsing because there are all sorts of reasons (prompts, Env, defaults, just as features. but also the split backends; deferring mapping to argparse was consistently a pain early on, caused code duplication and made it easy to have behavioral differences) why doing it at parse time is problematic.

It may still be possible...perhaps by scarily mutating the Args during parsing, or something I havent thought of yet, but i'm not yet certain whether it's a good enough idea to warrant the extra complexity.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 100.00%. Comparing base (cd24bfc) to head (6b4885e).
Report is 9 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff            @@
##              main      #112   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files           22        22           
  Lines         2012      2091   +79     
  Branches       442       462   +20     
=========================================
+ Hits          2012      2091   +79     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.