Add array conversion methods to ndarray (#21)

* Add array conversion methods to ndarray

* Fix array conversion methods after review

* Add tests for array conversion methods

* Cleanup tests for array conversion methods

Remove simple ones and leave comments for consistency

* Update type hints for ndarray.view

Its stub was splitted into all possible overloads.
`view(self, dtype: Type[_NdArraySubClass], type: Type[_NdArraySubClass])` could not be used.

Author: sproshev

numpy-stubs/__init__.pyi

@@ -6,6 +6,7 @@ from typing import (
     Any,
     Container,
     Dict,
+    IO,
     Iterable,
     List,
     Mapping,
@@ -71,6 +72,7 @@ _DtypeLike = Union[
     Tuple[_DtypeLikeNested, _DtypeLikeNested],
 ]
 
+_NdArraySubClass = TypeVar("_NdArraySubClass", bound=ndarray)
 
 class dtype:
     names: Optional[Tuple[str, ...]]
@@ -369,6 +371,46 @@ class ndarray(_ArrayOrScalarCommon, Iterable, Sized, Container):
     @strides.setter
     def strides(self, value: _ShapeLike): ...
 
+    # Array conversion
+    @overload
+    def item(self, *args: int) -> Any: ...
+    @overload
+    def item(self, args: Tuple[int, ...]) -> Any: ...
+    def tolist(self) -> List[Any]: ...
+    @overload
+    def itemset(self, __value: Any) -> None: ...
+    @overload
+    def itemset(self, __item: _ShapeLike, __value: Any) -> None: ...
+    def tostring(self, order: Optional[str]=...) -> bytes: ...
+    def tobytes(self, order: Optional[str]=...) -> bytes: ...
+    def tofile(self,
+               fid: Union[IO[bytes], str],
+               sep: str=...,
+               format: str=...) -> None: ...
+    def dump(self, file: str) -> None: ...
+    def dumps(self) -> bytes: ...
+    def astype(self,
+               dtype: _DtypeLike,
+               order: str=...,
+               casting: str=...,
+               subok: bool=...,
+               copy: bool=...) -> ndarray: ...
+    def byteswap(self, inplace: bool=...) -> ndarray: ...
+    def copy(self, order: str=...) -> ndarray: ...
+    @overload
+    def view(self, dtype: _DtypeLike=...) -> ndarray: ...
+    @overload
+    def view(self, dtype: Type[_NdArraySubClass]) -> _NdArraySubClass: ...
+    @overload
+    def view(self, dtype: _DtypeLike, type: Type[_NdArraySubClass]) -> _NdArraySubClass: ...
+    @overload
+    def view(self, *, type: Type[_NdArraySubClass]) -> _NdArraySubClass: ...
+    def getfield(self,
+                 dtype: Union[_DtypeLike, str],
+                 offset: int=...) -> ndarray: ...
+    def setflags(self, write: bool=..., align: bool=..., uic: bool=...) -> None: ...
+    def fill(self, value: Any) -> None: ...
+
     # Shape manipulation
     @overload
     def reshape(self, shape: Sequence[int], *, order: str=...) -> ndarray: ...

tests/pass/ndarray_conversion.py

@@ -0,0 +1,90 @@
+import numpy as np
+
+nd = np.array([[1, 2], [3, 4]])
+
+# item
+nd.item()  # `nd` should be one-element in runtime
+nd.item(1)
+nd.item(0, 1)
+nd.item((0, 1))
+
+# tolist is pretty simple
+
+# itemset
+nd.itemset(3)  # `nd` should be one-element in runtime
+nd.itemset(3, 0)
+nd.itemset((0, 0), 3)
+
+# tostring/tobytes
+nd.tostring()
+nd.tostring("C")
+nd.tostring(None)
+
+nd.tobytes()
+nd.tobytes("C")
+nd.tobytes(None)
+
+# tofile
+nd.tofile("a.txt")
+nd.tofile(open("a.txt", mode="bw"))
+
+nd.tofile("a.txt", "")
+nd.tofile("a.txt", sep="")
+
+nd.tofile("a.txt", "", "%s")
+nd.tofile("a.txt", format="%s")
+
+# dump is pretty simple
+# dumps is pretty simple
+
+# astype
+nd.astype("float")
+nd.astype(float)
+
+nd.astype(float, "K")
+nd.astype(float, order="K")
+
+nd.astype(float, "K", "unsafe")
+nd.astype(float, casting="unsafe")
+
+nd.astype(float, "K", "unsafe", True)
+nd.astype(float, subok=True)
+
+nd.astype(float, "K", "unsafe", True, True)
+nd.astype(float, copy=True)
+
+# byteswap
+nd.byteswap()
+nd.byteswap(True)
+
+# copy
+nd.copy()
+nd.copy("C")
+
+# view
+nd.view()
+nd.view(np.int64)
+nd.view(dtype=np.int64)
+nd.view(np.int64, np.matrix)
+nd.view(type=np.matrix)
+
+# getfield
+nd.getfield("float")
+nd.getfield(float)
+
+nd.getfield("float", 8)
+nd.getfield(float, offset=8)
+
+# setflags
+nd.setflags()
+
+nd.setflags(True)
+nd.setflags(write=True)
+
+nd.setflags(True, True)
+nd.setflags(write=True, align=True)
+
+nd.setflags(True, True, False)
+nd.setflags(write=True, align=True, uic=False)
+
+# fill is pretty simple

tests/reveal/ndarray_conversion.py

@@ -0,0 +1,54 @@
+import numpy as np
+
+nd = np.array([[1, 2], [3, 4]])
+
+# item
+reveal_type(nd.item())  # E: Any
+reveal_type(nd.item(1))  # E: Any
+reveal_type(nd.item(0, 1))  # E: Any
+reveal_type(nd.item((0, 1)))  # E: Any
+
+# tolist
+reveal_type(nd.tolist())  # E: builtins.list[Any]
+
+# itemset does not return a value
+# tostring is pretty simple
+# tobytes is pretty simple
+# tofile does not return a value
+# dump does not return a value
+# dumps is pretty simple
+
+# astype
+reveal_type(nd.astype("float"))  # E: numpy.ndarray
+reveal_type(nd.astype(float))  # E: numpy.ndarray
+reveal_type(nd.astype(float, "K"))  # E: numpy.ndarray
+reveal_type(nd.astype(float, "K", "unsafe"))  # E: numpy.ndarray
+reveal_type(nd.astype(float, "K", "unsafe", True))  # E: numpy.ndarray
+reveal_type(nd.astype(float, "K", "unsafe", True, True))  # E: numpy.ndarray
+
+# byteswap
+reveal_type(nd.byteswap())  # E: numpy.ndarray
+reveal_type(nd.byteswap(True))  # E: numpy.ndarray
+
+# copy
+reveal_type(nd.copy())  # E: numpy.ndarray
+reveal_type(nd.copy("C"))  # E: numpy.ndarray
+
+# view
+class SubArray(np.ndarray):
+    pass
+
+reveal_type(nd.view())  # E: numpy.ndarray
+reveal_type(nd.view(np.int64))  # E: numpy.ndarray
+# replace `Any` with `numpy.matrix` when `matrix` will be added to stubs
+reveal_type(nd.view(np.int64, np.matrix))  # E: Any
+reveal_type(nd.view(np.int64, SubArray))  # E: SubArray
+
+# getfield
+reveal_type(nd.getfield("float"))  # E: numpy.ndarray
+reveal_type(nd.getfield(float))  # E: numpy.ndarray
+reveal_type(nd.getfield(float, 8))  # E: numpy.ndarray
+
+# setflags does not return a value
+# fill does not return a value
+

tests/test_stubs.py

@@ -17,10 +17,13 @@ def get_test_cases(directory):
                 # Use relative path for nice py.test name
                 relpath = os.path.relpath(fullpath, start=directory)
                 skip_py2 = fname.endswith("_py3.py")
+                skip_py3 = fname.endswith("_py2.py")
 
                 for py_version_number in (2, 3):
                     if py_version_number == 2 and skip_py2:
                         continue
+                    if py_version_number == 3 and skip_py3:
+                        continue
                     py2_arg = ['--py2'] if py_version_number == 2 else []
 
                     yield pytest.param(