Seperate positional only and keyword only arguments in --help similar to argparse and typer

[Ravencentric]

This request is simply an aesthetic change regarding the help screen
argparse and typer seperate the postional and keyword arguments in the help screen. I personally find the seperation to be more readable.

argparse:

juicenet --help
Usage: myapp [-h] 

myapp for foobar

Positional Arguments:
  <path>                file or directory

Options:
  -h, --help            show this help message and exit

typer:

python .\test2.py --help

 Usage: test2.py [OPTIONS] [PATH]

╭─ Arguments ──────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│   path      [PATH]  The path to use [default: .]                                                                     │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --flag    --no-flag      The flag to use [default: no-flag]                                                          │
│ --help                   Show this message and exit.                                                                 │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

cyclopts:

python .\test.py --help
Usage: cli [ARGS] [OPTIONS]

╭─ Parameters ─────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ PATH           directory or file [default: C:\Users\raven\Documents\GitHub\testtesttest]                             │
│ --config       config file [default: C:\Users\raven\Documents\GitHub\testtesttest\config.yaml]                       │
│ --version      Display application version.                                                                          │
│ --help     -h  Display this message and exit.                                                                        │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

I have explicitly defined path as positional only and config as keyword only

@app.default() # type: ignore
def cli(
    path: Annotated[
        Path, 
        Parameter(
            help="directory or file",
            validator=validators.Path(exists=True))
        ] = Path.cwd(),
    /, # path is positional only
    *, # all arguments after this are keyword only
    config: Annotated[
        Path, 
        Parameter(
            name=["--config"], 
            help="config file", 
            validator=validators.Path(exists=True))
        ] = Path.cwd() / "config.yaml",
) -> None:
    print(f"{path = }")
    print(f"{config = }")

Apologies if im bombarding you with issues! I've just started to play with cyclopts (really liking it)

[BrianPugh]

Keep the issues coming! I appreciate you using CYclopts, and It's easier to make larger changes at the beginning of a project :D.

To be concrete, would the proposed output look like:

$ python .\test.py --help
Usage: cli [ARGS] [OPTIONS]

╭─ Arguments ──────────────────────────────────────────────────────────────────────────────────────────╮
│ PATH           directory or file [default: C:\Users\raven\Documents\GitHub\testtesttest]             │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Parameters ─────────────────────────────────────────────────────────────────────────────────────────╮
│ --config       config file [default: C:\Users\raven\Documents\GitHub\testtesttest\config.yaml]       │
│ --version      Display application version.                                                          │
│ --help     -h  Display this message and exit.                                                        │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────╯

I suppose the issue is, where would a POSITIONAL_OR_KEYWORD argument go?

[Ravencentric]

To be concrete, would the proposed output look like:

yes

I suppose the issue is, where would a POSITIONAL_OR_KEYWORD argument go?

obvious answer would be a third box maybe? but will it go in between or last? will it be too much clutter?

Another option would just be rolling POSITIONAL_OR_KEYWORD into the Parameters box in the help screen to encourage users to use keyworded args where possible, since too many positional arguments get confusing real quick and more prone to mistakes (my personal preference would be this)

[BrianPugh]

So I think this could work (where config is POSITIONAL_OR_KEYWORD). I'm worried that it might too heavily encourage the use of POSITIONAL_ONLY values. In most of my CLI applications, I primarily use POSITIONAL_OR_KEYWORD or KEYWORD_ONLY, but I rarely use POSITIONAL_ONLY.

╭─ Arguments ────────────────────────────────────────────────────────────────────────────────────────────╮
│ PATH           directory or file [default: C:\Users\raven\Documents\GitHub\testtesttest]               │
╰────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Parameters ───────────────────────────────────────────────────────────────────────────────────────────╮
│ CONFIG,--config  config file [default: C:\Users\raven\Documents\GitHub\testtesttest\config.yaml]       │
│ --version        Display application version.                                                          │
│ --help     -h    Display this message and exit.                                                        │
╰────────────────────────────────────────────────────────────────────────────────────────────────────────╯

[Ravencentric]

that looks good, conveys config is both without being too much clutter

From my experience, usually CLIs usually have atmost one or two positional only args, with the rest mostly being keyword only or keyword_or_positional. And for keyword_or_positional i usually explicitly do keyword to avoid any mistakes.

[BrianPugh]

Closing this issue to centralize discussion over to #39.