feat: Add ability to define custom action callable.

[DanCardin]

Attempt at addressing issue described in #7, where one cannot replicate --help/--version alike arguments. basically, you'd supply a callable as an action and raise Exit.

But i think the idea as implemented has some other nice side-effects. when using the native backend, it can use the invoke system to dependency-inject parser state very easily. the main question is whether or not it's a good idea to expose that parser state to downstream consumers.

It's certainly useful inside the parser itself to send arguments to the native handlers, so 🤷

[coveralls]

Pull Request Test Coverage Report for Build 6590645774

• 94 of 94 (100.0%) changed or added relevant lines in 4 files are covered.
• No unchanged relevant lines lost coverage.
• Overall coverage remained the same at 100.0%

---

Totals
Change from base Build 6589255068:	0.0%
Covered Lines:	1536
Relevant Lines:	1536

---

💛 - Coveralls

[pawamoy]

When using the cappa backend: cappa.Command, cappa.Arg, cappa.backend.ParseContext,
cappa.backend.Value are acceptable input values. They'll be automatically injected
into the action callable.

An example here would help a lot to understand.

IIUC with the cappa backend one can do:

def foo(
    origin_command: cappa.Command,
    origin_arg: cappa.Arg,
    context: cappa.backend.ParseContext,
    backend_value: cappa.backend.Value,
):
    # use these args as you see fit
    raise cappa.Exit("message")


@dataclass
class Args:
    foo: Annotated[str, cappa.Arg(action=foo, short=True)]

...with arbitrary argument names or positions since their values will be injected based on their type.

Is that correct?

It would be great if these 4 mentioned classes linked to their respective API docs (I'm not sure what cappa.backend.Value represents).

[DanCardin]

...with arbitrary argument names or positions since their values will be injected based on their type.

Is that correct?

It would be great if these 4 mentioned classes linked to their respective API docs (I'm not sure what cappa.backend.Value represents).

Right, it's like an invoke-equivalent to the arguments you get when subclassing an argparse Action on the __call__ method.

I left the objects somewhat intentionally undocumented because this feature makes those objects part of the public interface of the library, and i'm not confident (especially with ParseContext) that they wont have breaking changes.

I suppose I can just leave those objects out of the docs...in fact yes that's what I'll do.

[pawamoy]

Yes, that sounds good 🙂

[DanCardin]

In fact, it turns out I can get argparse to supply Arg, Value, and Command. It now just leaves off documenting the parser context