This is a complete outsider’s perspective but

(a) it would be good if NumPy type annotations could include an “array_like” type that allows lists, tuples, etc.
(b) I’ve always thought (since PEP561) that it would be cool for type annotations to replace compiler type annotations for e.g. Cython and Numba. Is this in the realm of possibility for the future?


On 26 Nov 2017, 3:54 AM +1100, Charles R Harris <>, wrote:

On Sat, Nov 25, 2017 at 1:14 AM, Stephan Hoyer <> wrote:
There's been growing interest in supporting PEP-484 style type annotations in NumPy:

This would allow NumPy users to add type-annotations to their code that uses NumPy, which they could check with mypy, pycharm or pytype. For example:

def f(x: np.ndarray) -> np.ndarray:
    """Identity function on a NumPy array."""
    return x

Eventually, we could include data types and potentially array shapes as part of the type. This gets quite a bit more complicated, and to do in a really satisfying way would require new features in Python's typing system. To help guide discussion, I wrote a doc describing use-cases and needs for typing array shapes in more detail:

Nathaniel Smith and I recently met with group in San Francisco interested in this topic, including several mypy/typeshed developers (Jelle Zijlstra and Ethan Smith). We discussed and came up with a plan for moving forward:
1. Release basic type stubs for numpy.ndarray without dtypes or shapes, as separate "numpy_stubs" package on PyPI per PEP 561. This will let us iterate rapidly on (experimental) type annotations without coupling to NumPy's release cycle.
2. Add support for dtypes in ndarray type-annotations. This might be as simple as writing np.ndarray[np.float64], but will need a decision about appropriate syntax for shape typing to ensure that this is forwards compatible with typing shapes. Note: this will likely require minor changes to NumPy itself, e.g., to add __class_getitem__ per PEP 560.
3. Add support for shapes in ndarray type-annotations, and define a broader standard for typing array shapes. This will require collaboration with type-checker developers on the required typing features (for details, see my doc above). Eventually, this may entail writing a PEP.

Can you make a case for the usefulness numpy annotations? What benefits to you want to achieve and how will annotation aid in getting there.

NumPy-Discussion mailing list