deprecate to_numpy and from_numpy

Author: alexfikl

arraycontext/container/traversal.py

@@ -881,37 +881,24 @@ def from_numpy(
 
     The conversion is done using :meth:`arraycontext.ArrayContext.from_numpy`.
     """
-    def _from_numpy_with_check(subary: Union[np.ndarray, ScalarLike]) \
-            -> ArrayOrContainerOrScalar:
-        if isinstance(subary, np.ndarray) or np.isscalar(subary):
-            return actx.from_numpy(subary)
-        else:
-            raise TypeError(f"array is not an ndarray: '{type(subary).__name__}'")
+    warn("Calling from_numpy(ary, actx) is deprecated, call actx.from_numpy(ary)"
+         " instead. This will stop working in 2023.",
+         DeprecationWarning, stacklevel=2)
 
-    return rec_map_array_container(_from_numpy_with_check, ary)
+    return actx.from_numpy(ary)
 
 
-def to_numpy(ary: ArrayOrContainer, actx: ArrayContext) -> Any:
+def to_numpy(ary: ArrayOrContainer, actx: ArrayContext) -> ArrayOrContainer:
     """Convert all arrays in the :class:`~arraycontext.ArrayContainer` to
     :mod:`numpy` using the provided :class:`~arraycontext.ArrayContext` *actx*.
 
     The conversion is done using :meth:`arraycontext.ArrayContext.to_numpy`.
     """
-    def _to_numpy_with_check(subary: Any) -> Any:
-        if isinstance(subary, actx.array_types) or np.isscalar(subary):
-            # NOTE: these are allowed by np.isscalar, but not here
-            assert not isinstance(subary, (str, bytes))
-
-            return actx.to_numpy(subary)
-        else:
-            raise TypeError(
-                    f"array of type '{type(subary).__name__}' not in "
-                    f"supported types {actx.array_types}")
+    warn("Calling to_numpy(ary, actx) is deprecated, call actx.to_numpy(ary)"
+         " instead. This will stop working in 2023.",
+         DeprecationWarning, stacklevel=2)
 
-    return rec_map_array_container(_to_numpy_with_check,
-                                   # do a freeze first, if 'actx' supports
-                                   # container-wide freezes
-                                   actx.thaw(actx.freeze(ary)))
+    return actx.to_numpy(ary)
 
 # }}}
 

arraycontext/context.py

@@ -221,6 +221,8 @@ def dtype(self) -> "np.dtype[Any]":
         "ArrayOrContainerOrScalarT",
         bound=ArrayOrContainerOrScalar)
 
+NumpyOrContainerOrScalar = Union[np.ndarray, "ArrayContainer", ScalarLike]
+
 # }}}
 
 
@@ -304,25 +306,28 @@ def zeros_like(self, ary: Array) -> Array:
 
     @abstractmethod
     def from_numpy(self,
-                   array: Union["np.ndarray[Any, Any]", ScalarLike]
-                   ) -> Union[Array, ScalarLike]:
+                   array: ArrayOrContainerOrScalar
+                   ) -> NumpyOrContainerOrScalar:
         r"""
         :returns: the :class:`numpy.ndarray` *array* converted to the
             array context's array type. The returned array will be
-            :meth:`thaw`\ ed.
+            :meth:`thaw`\ ed. When working with array containers each leaf
+            must be an :class:`~numpy.ndarray` or scalar, which is then converted
+            to the context's array type leaving the container structure
+            intact.
         """
-        pass
 
     @abstractmethod
     def to_numpy(self,
-                 array: Union[Array, ScalarLike]
-                 ) -> Union["np.ndarray[Any, Any]", ScalarLike]:
+                 array: NumpyOrContainerOrScalar
+                 ) -> ArrayOrContainerOrScalar:
         r"""
-        :returns: *array*, an array recognized by the context, converted
-            to a :class:`numpy.ndarray`. *array* must be
-            :meth:`thaw`\ ed.
+        :returns: an :class:`numpy.ndarray` for each array recognized by the
+            context. The input *array* must be :meth:`thaw`\ ed.
+            When working with array containers each leaf must be one of
+            the context's array types or a scalar, which is then converted to
+            an :class:`~numpy.ndarray` leaving the container structure intact.
         """
-        pass
 
     @abstractmethod
     def call_loopy(self,
@@ -351,8 +356,6 @@ def freeze(self, array: ArrayOrContainerOrScalarT) -> ArrayOrContainerOrScalarT:
         Freezing makes the array independent of this :class:`ArrayContext`;
         it is permitted to :meth:`thaw` it in a different one, as long as that
         context understands the array format.
-
-        See also :func:`arraycontext.freeze`.
         """
 
     @abstractmethod
@@ -366,8 +369,6 @@ def thaw(self, array: ArrayOrContainerOrScalarT) -> ArrayOrContainerOrScalarT:
         the data in *array*.
 
         The returned array may not be used with other contexts while thawed.
-
-        See also :func:`arraycontext.thaw`.
         """
 
     def freeze_thaw(
@@ -387,10 +388,11 @@ def freeze_thaw(
     @abstractmethod
     def tag(self,
             tags: ToTagSetConvertible,
-            array: ArrayT) -> ArrayT:
+            array: ArrayOrContainerOrScalarT) -> ArrayOrContainerOrScalarT:
         """If the array type used by the array context is capable of capturing
         metadata, return a version of *array* with the *tags* applied. *array*
-        itself is not modified.
+        itself is not modified. When working with array containers, the
+        tags are applied to each leaf of the container.
 
         See :ref:`metadata` as well as application-specific metadata types.
 
@@ -400,10 +402,11 @@ def tag(self,
     @abstractmethod
     def tag_axis(self,
                  iaxis: int, tags: ToTagSetConvertible,
-                 array: ArrayT) -> ArrayT:
+                 array: ArrayOrContainerOrScalarT) -> ArrayOrContainerOrScalarT:
         """If the array type used by the array context is capable of capturing
         metadata, return a version of *array* in which axis number *iaxis* has
-        the *tags* applied. *array* itself is not modified.
+        the *tags* applied. *array* itself is not modified. When working with
+        array containers, the tags are applied to each leaf of the container.
 
         See :ref:`metadata` as well as application-specific metadata types.