Annotated metadata on a list's element type

[mcoughlin]

First Check

• I added a very descriptive title here.
• I used the GitHub search to find a similar question and didn't find it.
• I searched the documentation, with the integrated search.
• I already searched in Google "How to X" and didn't find any information.
• I already read and followed all the tutorials in the docs and didn't find an answer.

Example Code

from typing import Annotated
import typer

app = typer.Typer()

@app.command()
def main(x: Annotated[list[Annotated[int, "meta"]], typer.Option()] = []):
    print(x)

app()

Description

The code results in:
AssertionError: List types with complex sub-types are not currently supported

Typer honours Annotated metadata on a scalar parameter's type, but asserts when the same type appears as a list element.

We use Astropy quantities, where the way to pin a unit or a physical type to a type is Annotated metadata:
u.Quantity[u.s] == Annotated[Quantity, Unit("s")]. So the natural spelling of "a repeatable option that takes times" is

Annotated[list[u.Quantity[u.physical.time]], typer.Option()]

which is rejected, while the scalar equivalent is fine.

We currently work around it by putting the metadata on the outer Annotated instead, which parses but reads oddly:
Annotated[list[u.Quantity], u.physical.time, typer.Option()]

Operating System

macOS

Operating System Details

No response

Project Version

Typer 0.27.2

Python Version

3.12

Additional Context

No response

[Kxrma47]

The assertion is a Typer limitation for a complex list element type; moving the metadata to the outer Annotated changes its meaning and does not make per-element metadata supported. If you need a repeatable --x now, accept strings and validate each value explicitly:

from typing import Annotated
import typer
from astropy import units as u

app = typer.Typer()

@app.command()
def main(x: Annotated[list[str] | None, typer.Option()] = None):
    times = [u.Quantity(raw).to(u.s) for raw in (x or [])]
    print(times)

if __name__ == '__main__':
    app()
# e.g. --x '5 s' --x '2 min'

.to(u.s) rejects incompatible physical dimensions. This is a workaround, not support for list[Annotated[...]]; retaining the original type annotation would require a Typer change. Typer repeatable options · Astropy string quantities

[wmorin]

Typer only unwraps the outer Annotated. For list params, get_click_param in typer/main.py takes the element type and does assert not get_origin(main_type), and get_origin(Annotated[int, "meta"]) is Annotated, so the assert fires whatever the metadata is. u.Quantity[u.physical.time] is an Annotated alias, so it hits the same thing. I don't think there's a way around it in 0.27.2 short of a fix in Typer (stripping Annotated off the element before that check).

In the meantime I'd drop the metadata from the type and pass a parser instead. Typer calls it once per value, so you still get a repeatable option, the values come back as real Quantity objects, and a wrong unit becomes a normal CLI error:

from typing import Annotated
import typer
from astropy import units as u

def time_quantity(value: str) -> u.Quantity:
    q = u.Quantity(value)
    if q.unit.physical_type != u.physical.time:
        raise typer.BadParameter(f"{value!r} is not a time")
    return q

app = typer.Typer()

@app.command()
def main(x: Annotated[list[u.Quantity], typer.Option(parser=time_quantity)] = []):
    print([q.to(u.s) for q in x])

app()

$ python app.py --x '5 s' --x '2 min'
[<Quantity 5. s>, <Quantity 120. s>]
$ python app.py --x '3 m'
Invalid value for '--x': '3 m' is not a time

Tried it on typer 0.27.2 / Python 3.12. Note you can't keep list[u.Quantity[u.physical.time]] and add the parser on top, it still asserts since the check runs first.