[Numpy-discussion] Type annotations for NumPy

[Stephan Hoyer]

There's been growing interest in supporting PEP-484 style type annotations
in NumPy: https://github.com/numpy/numpy/issues/7370

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:
https://docs.google.com/document/d/1vpMse4c6DrWH5rq2tQSx3qwP_m_0lyn-Ij4WHqQqRHY

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.

I'm writing to gauge support for this general plan, and specifically to get
support for step 1.

Cheers,
Stephan
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/numpy-discussion/attachments/20171125/5339bcc7/attachment.html>