Wide vs. Narrow Types Documentation clarification

[diego-pm]

This part in the documentation is not clear to me.

Where it says List[int], shouldn't it be List[Union[str, int]]?

[erictraut]

Converting to discussion because it's a question, not a feature request or bug report.

[erictraut]

The documentation is correct here. If a parameter is marked as Sequence[str | int], it can accept a list[int] or a list[str] or a list[int | str] argument.

from collections.abc import Sequence

def func1(val: Sequence[str | int]):
    ...

def func2(a: list[int], b: list[str], c: list[str | int]):
    func1(a)
    func1(b)
    func1(c)

[diego-pm]

So that is what I was saying, if the Sequence[str|int] can accept list[str|int], then the docs should say:

A parameter that is typed as Sequence[Union[str, int]] can accept a List[Union[str,int]], Sequence[str], and a Sequence[int]

Instead of

A parameter that is typed as Sequence[Union[str, int]] can accept a List[int], Sequence[str], and a Sequence[int]

[erictraut]

A parameter typed as Sequence[Union[str, int]] can accept a List[int]. That's the point this documentation is trying to make — that Sequence is covariant, so it allows subtypes for its type argument. Since int is a subtype of Union[int, str], the type List[int] can be assigned to type Sequence[Union[str, int]].

You are correct that a Sequence[Union[str, int]] can also accept an argument of type List[Union[str, int]], but that's already obvious to most people. The documentation is trying to explain why List[int] is also compatible.

[diego-pm]

For me (quite new to typings), it is more obvious that Sequence[Union[str, int]] accepts List[int] than List[Union[str|int]]. So from a typing beginner point of view person, I thought changing this would make the docs clearer to other beginner people.

[erictraut]

OK, I updated the documentation to include both List[Union[str, int]] and List[int] in that sentence. Both of them are compatible with Sequence[Union[str, int]].