Named arguments with multiple values, e.g. list[str]

[peterjc]

Sample code

from cyclopts import App, Parameter
from typing import Annotated

app = App()


@app.default
def main(
    *, input: Annotated[list[str], Parameter(help="Input filename(s)")] = None
) -> None:
    """Process the input files."""
    if input is None:
        print("Not told what to do")
        return 1
    elif not input:
        print("Told to do nothing")
        return 0
    else:
        print("Working:")
        for file in input:
            print(f"* {file}")
        return 0


app()

Testing with cyclopts 3.1.1 on Python 3.12.7 on macOS.

This example works mostly as expected:

base ❯ python cyclopts_demo.py --help
Usage: main COMMAND [OPTIONS]

Process the input files.

╭─ Commands ──────────────────────────────────────────────────────╮
│ --help -h  Display this message and exit.                       │
│ --version  Display application version.                         │
╰─────────────────────────────────────────────────────────────────╯
╭─ Parameters ────────────────────────────────────────────────────╮
│ --input --empty-input  Input filename(s)                        │
╰─────────────────────────────────────────────────────────────────╯

❯ python cyclopts_demo.py
Not told what to do

This works as a way to set an empty list:

❯ python cyclopts_demo.py --empty-input
Told to do nothing

Now with a single argument:

❯ python cyclopts_demo.py --input A.txt
Working:
* A.txt

Passing multiple arguments this way works:

❯ python cyclopts_demo.py --input A.txt --input B.txt
Working:
* A.txt
* B.txt

However, the natural argparse supported syntax does not:

❯ python cyclopts_demo.py --input A.txt B.txt
╭─ Error ─────────────────────────────────────────────────────────╮
│ Unused Tokens: ['B.txt'].                                       │
╰─────────────────────────────────────────────────────────────────╯

This syntax is especially useful when combined with wildcards, --input *.txt for example.

Is this me using cyclopts wrong, or do you have the same limitation as click and typer?

• DOC: Documentation of passing multiple values in "option" vs "argument" isn't sufficiently explicit fastapi/typer#554
• Allow @click.option(nargs=-1) pallets/click#484

[peterjc]

I think I found the answer in your docs:

from cyclopts import App, Parameter
from typing import Annotated

app = App()


@app.default
def main(
    *,
    input: Annotated[
        list[str], Parameter(help="Input filename(s)", consume_multiple=True)
    ] = None,
) -> None:
    """Process the input files."""
    if input is None:
        print("Not told what to do")
        return 1
    elif not input:
        print("Told to do nothing")
        return 0
    else:
        print("Working:")
        for file in input:
            print(f"* {file}")
        return 0


app()

❯ python cyclopts_demo.py --input A.txt B.txt
Working:
* A.txt
* B.txt

Hooray! This deserves highlighting on https://cyclopts.readthedocs.io/en/latest/vs_typer/README.html in my opinion (as it looks to solve my number one frustration with Typer!)

[BrianPugh]

glad you were able to figure it out! Any recommendations on how to improve the docs (I'm very open to PRs as well!)? I don't think this feature is quite "bold" enough to make it to the README, but I certainly want all of Cyclopts information/features to be more readily available to users.

[peterjc]

I didn't mean the top level https://github.com/BrianPugh/cyclopts/blob/main/README.md but as another page under https://cyclopts.readthedocs.io/en/latest/vs_typer/README.html

i.e. A sister page to entries like https://cyclopts.readthedocs.io/en/latest/vs_typer/help_defaults/README.html about the help defaults (another annoyance with typer where your defaults are better, cross reference typer issue 465).

I would explicitly reference the argparse nargs equivalence https://docs.python.org/dev/library/argparse.html#nargs for an indeterminate number of arguments.

[BrianPugh]

Got it! I'll add that soon, thanks for the recommendation!

[BrianPugh]

Addressed in #269