The generated documentation:
https://17825-908607-gh.circle-artifacts.com/0/doc/build/html/reference/typing.html#numpy.typing.NestedSequence

I can see this being nice to have, so I am not opposed. But I am a bit surprised that we want to make nested sequences a common thing for most command? I.e. I would expect it to be mainly a valid input for np.array and friends, and pretty much all other occurrences would require you to call np.asarray manually to type correctly?

I.e. I would expect it to be mainly a valid input for np.array and friends, and pretty much all other occurrences would require you to call np.asarray manually to type correctly?

This is true for scripts that utilize np.array, but if np.array is called under the hood by some function then there is no easy way to reuse its annotations. Barring the case the where its is signatures is absolutely identical, that is (i.e. situations where we can abuse __call__-based protocols).

import numpy as np

# No easy way of grabbing the signature of `np.array` and putting it in `func` 
# (besides manually copying it, that is)
def func(a):  # ??? 
    return np.array(a) * 10

In practice this means that, unfortunately, we're stuck with quite a bit code duplication and thus the need for the likes of NestedSequence. Hence why I feel that making it public would worthwhile, especially for downstream libraries.

Closing this for now, as further testing has unfortunately revealed a number of detrimental mypy bugs/limitations 😕 :

• NestedSequence fails as function annotation if the, respective, passed parameter has previously
  not been assigned and/or declared.

from typing import TypeVar, List, overload
import numpy.typing as npt

@overload
def func1(a: npt.NestedSequence[bool]) -> bool: ...
@overload
def func1(a: npt.NestedSequence[int]) -> int: ...

int1 = [[1]]
int2: List[List[int]]

# note: Revealed type is 'builtins.int'
# This is ok
reveal_type(func1(int1))

# note: Revealed type is 'builtins.int'
# This is also ok
reveal_type(func1(int2))

# note: Revealed type is 'builtins.bool'
# This is bad; how did we end up at the `bool` overload all of a sudden????
reveal_type(func1([[1]]))  

• The use of TypeVars is just straight-up broken.

T = TypeVar("T")

def func2(a: npt.NestedSequence[T]) -> T: ...

# error: Argument 1 to "func2" has incompatible type "List[List[int]]"; expected "NestedSequence[<nothing>]"
reveal_type(func2(int1))

# error: Argument 1 to "func2" has incompatible type "List[List[int]]"; expected "NestedSequence[<nothing>]"
reveal_type(func2(int2))

# note: Revealed type is 'Any'
reveal_type(func2([[1]]))