Explainer on what is supported

Issue with current documentation:

Not necessarily related to numtype but NumPy typing in general. I'm a bit confused as to what is expected to work in user code and what isn't. Is there some documentation which explains this? Perhaps a page or simple list of features would help elucidate this for users.

As a concrete example - I'd like a type checker to be able to pick up this example related to reducing rank of the array. This should fail, but currently passes with mypy v1.19.1 NumPy v2.4.0 Python 3.14. Is this sort of thing even possible without language changes or runtime typing? Is support for this on the horizon?

from typing import NewType
from numpy import ndarray
import numpy as np

A = NewType("A", int)
B = NewType("B", int)
C = NewType("C", int)
type U8 = np.dtype[np.uint8]

# Should fail - currently pass. Actual returned type is `ndarray[tuple[B], U8]`
def f1(a: ndarray[tuple[A, B, C], U8]) -> ndarray[tuple[A, B], U8]:
    return a[:, 2, :]

rng = np.random.default_rng(0)
a: ndarray[tuple[A, B, C], U8] = rng.integers(0, 100, size=(10, 20, 30), dtype=np.uint8)
print(f1(a).shape)

By contrast this correctly fails with mypy

# Should fail - correctly fails
# error: Incompatible return value type (got "ndarray[tuple[A, B, C], dtype[unsignedinteger[_8Bit]]]", expected "ndarray[tuple[A, C, B], dtype[unsignedinteger[_8Bit]]]")  [return-value]
def f2(a: ndarray[tuple[A, B, C], U8]) -> ndarray[tuple[A, C, B], U8]:
    return a + 2

a: ndarray[tuple[A, B, C], U8] = rng.integers(0, 100, size=(10, 20, 30), dtype=np.uint8)
print(f2(a).shape)

Idea or request for content:

No response

No files or tests are named in the issue. Start by reviewing the existing NumPy typing documentation and the two mypy examples, then determine which behaviors and limitations should be documented. Done means a clear explanation or feature list covering supported typing behavior and the rank-reduction case.