DEPR: Raise FutureWarning about raising an error in __array__ when copy=False cannot be honored

doc/source/whatsnew/v2.3.0.rst

@@ -34,7 +34,7 @@ Other enhancements
 
 - The semantics for the ``copy`` keyword in ``__array__`` methods (i.e. called
   when using ``np.array()`` or ``np.asarray()`` on pandas objects) has been
-  updated to work correctly with NumPy >= 2 (:issue:`57739`)
+  updated to raise FutureWarning with NumPy >= 2 (:issue:`60340`)
 - The :meth:`~Series.sum` reduction is now implemented for ``StringDtype`` columns (:issue:`59853`)
 -
 

pandas/core/arrays/arrow/array.py

@@ -12,6 +12,7 @@
     cast,
 )
 import unicodedata
+import warnings
 
 import numpy as np
 
@@ -28,6 +29,7 @@
     pa_version_under13p0,
 )
 from pandas.util._decorators import doc
+from pandas.util._exceptions import find_stack_level
 from pandas.util._validators import validate_fillna_kwargs
 
 from pandas.core.dtypes.cast import (
@@ -663,9 +665,14 @@ def __array__(
     ) -> np.ndarray:
         """Correctly construct numpy arrays when passed to `np.asarray()`."""
         if copy is False:
-            # TODO: By using `zero_copy_only` it may be possible to implement this
-            raise ValueError(
-                "Unable to avoid copy while creating an array as requested."
+            warnings.warn(
+                "Starting on NumPy 2.0, the behavior of the 'copy' keyword has changed "
+                "and passing 'copy=False' raises an error when a zero-copy NumPy array "
+                "is not possible, Pandas will follow this behavior starting with "
+                "version 3.0. This conversion to NumPy requires a copy, but "
+                "'copy=False' was passed. Consider using 'np.asarray(..)' instead.",
+                FutureWarning,
+                stacklevel=find_stack_level(),
             )
         elif copy is None:
             # `to_numpy(copy=False)` has the meaning of NumPy `copy=None`.

pandas/core/arrays/categorical.py

@@ -1672,8 +1672,14 @@ def __array__(
         array(['a', 'b'], dtype=object)
         """
         if copy is False:
-            raise ValueError(
-                "Unable to avoid copy while creating an array as requested."
+            warnings.warn(
+                "Starting on NumPy 2.0, the behavior of the 'copy' keyword has changed "
+                "and passing 'copy=False' raises an error when a zero-copy NumPy array "
+                "is not possible, Pandas will follow this behavior starting with "
+                "version 3.0. This conversion to NumPy requires a copy, but "
+                "'copy=False' was passed. Consider using 'np.asarray(..)' instead.",
+                FutureWarning,
+                stacklevel=find_stack_level(),
             )
 
         ret = take_nd(self.categories._values, self._codes)

pandas/core/arrays/datetimelike.py

@@ -359,9 +359,17 @@ def __array__(
         # used for Timedelta/DatetimeArray, overwritten by PeriodArray
         if is_object_dtype(dtype):
             if copy is False:
-                raise ValueError(
-                    "Unable to avoid copy while creating an array as requested."
+                warnings.warn(
+                    "Starting on NumPy 2.0, the behavior of the 'copy' keyword has "
+                    "changed and passing 'copy=False' raises an error when a zero-copy "
+                    "NumPy array is not possible, Pandas will follow this behavior "
+                    "starting with version 3.0. This conversion to NumPy requires a "
+                    "copy, but 'copy=False' was passed. Consider using "
+                    "'np.asarray(..)' instead.",
+                    FutureWarning,
+                    stacklevel=find_stack_level(),
                 )
+
             return np.array(list(self), dtype=object)
 
         if copy is True:

pandas/core/arrays/interval.py

@@ -42,6 +42,7 @@
 from pandas.compat.numpy import function as nv
 from pandas.errors import IntCastingNaNError
 from pandas.util._decorators import Appender
+from pandas.util._exceptions import find_stack_level
 
 from pandas.core.dtypes.cast import (
     LossySetitemError,
@@ -1575,8 +1576,14 @@ def __array__(
         objects (with dtype='object')
         """
         if copy is False:
-            raise ValueError(
-                "Unable to avoid copy while creating an array as requested."
+            warnings.warn(
+                "Starting on NumPy 2.0, the behavior of the 'copy' keyword has changed "
+                "and passing 'copy=False' raises an error when a zero-copy NumPy array "
+                "is not possible, Pandas will follow this behavior starting with "
+                "version 3.0. This conversion to NumPy requires a copy, but "
+                "'copy=False' was passed. Consider using 'np.asarray(..)' instead.",
+                FutureWarning,
+                stacklevel=find_stack_level(),
             )
 
         left = self._left

pandas/core/arrays/masked.py

@@ -38,6 +38,7 @@
 )
 from pandas.errors import AbstractMethodError
 from pandas.util._decorators import doc
+from pandas.util._exceptions import find_stack_level
 from pandas.util._validators import validate_fillna_kwargs
 
 from pandas.core.dtypes.base import ExtensionDtype
@@ -604,8 +605,15 @@ def __array__(
             if not self._hasna:
                 # special case, here we can simply return the underlying data
                 return np.array(self._data, dtype=dtype, copy=copy)
-            raise ValueError(
-                "Unable to avoid copy while creating an array as requested."
+
+            warnings.warn(
+                "Starting on NumPy 2.0, the behavior of the 'copy' keyword has changed "
+                "and passing 'copy=False' raises an error when a zero-copy NumPy array "
+                "is not possible, Pandas will follow this behavior starting with "
+                "version 3.0. This conversion to NumPy requires a copy, but "
+                "'copy=False' was passed. Consider using 'np.asarray(..)' instead.",
+                FutureWarning,
+                stacklevel=find_stack_level(),
             )
 
         if copy is None:

pandas/core/arrays/period.py

@@ -415,8 +415,14 @@ def __array__(
                 return np.array(self.asi8, dtype=dtype)
 
         if copy is False:
-            raise ValueError(
-                "Unable to avoid copy while creating an array as requested."
+            warnings.warn(
+                "Starting on NumPy 2.0, the behavior of the 'copy' keyword has changed "
+                "and passing 'copy=False' raises an error when a zero-copy NumPy array "
+                "is not possible, Pandas will follow this behavior starting with "
+                "version 3.0. This conversion to NumPy requires a copy, but "
+                "'copy=False' was passed. Consider using 'np.asarray(..)' instead.",
+                FutureWarning,
+                stacklevel=find_stack_level(),
             )
 
         if dtype == bool:

pandas/core/arrays/sparse/array.py

@@ -562,8 +562,14 @@ def __array__(
                 return self.sp_values
 
         if copy is False:
-            raise ValueError(
-                "Unable to avoid copy while creating an array as requested."
+            warnings.warn(
+                "Starting on NumPy 2.0, the behavior of the 'copy' keyword has changed "
+                "and passing 'copy=False' raises an error when a zero-copy NumPy array "
+                "is not possible, Pandas will follow this behavior starting with "
+                "version 3.0. This conversion to NumPy requires a copy, but "
+                "'copy=False' was passed. Consider using 'np.asarray(..)' instead.",
+                FutureWarning,
+                stacklevel=find_stack_level(),
             )
 
         fill_value = self.fill_value

pandas/core/generic.py

@@ -2151,9 +2151,15 @@ def __array__(
     ) -> np.ndarray:
         if copy is False and not self._mgr.is_single_block and not self.empty:
             # check this manually, otherwise ._values will already return a copy
-            # and np.array(values, copy=False) will not raise an error
-            raise ValueError(
-                "Unable to avoid copy while creating an array as requested."
+            # and np.array(values, copy=False) will not raise a warning
+            warnings.warn(
+                "Starting on NumPy 2.0, the behavior of the 'copy' keyword has changed "
+                "and passing 'copy=False' raises an error when a zero-copy NumPy array "
+                "is not possible, Pandas will follow this behavior starting with "
+                "version 3.0. This conversion to NumPy requires a copy, but "
+                "'copy=False' was passed. Consider using 'np.asarray(..)' instead.",
+                FutureWarning,
+                stacklevel=find_stack_level(),
             )
         values = self._values
         if copy is None:

pandas/core/indexes/multi.py

@@ -1314,8 +1314,14 @@ def __array__(self, dtype=None, copy=None) -> np.ndarray:
         """the array interface, return my values"""
         if copy is False:
             # self.values is always a newly construct array, so raise.
-            raise ValueError(
-                "Unable to avoid copy while creating an array as requested."
+            warnings.warn(
+                "Starting on NumPy 2.0, the behavior of the 'copy' keyword has changed "
+                "and passing 'copy=False' raises an error when a zero-copy NumPy array "
+                "is not possible, Pandas will follow this behavior starting with "
+                "version 3.0. This conversion to NumPy requires a copy, but "
+                "'copy=False' was passed. Consider using 'np.asarray(..)' instead.",
+                FutureWarning,
+                stacklevel=find_stack_level(),
             )
         if copy is True:
             # explicit np.array call to ensure a copy is made and unique objects

pandas/tests/arrays/sparse/test_array.py

@@ -500,8 +500,12 @@ def test_array_interface(arr_data, arr):
         # copy=False semantics are only supported in NumPy>=2.
         return
 
-    # for sparse arrays, copy=False is never allowed
-    with pytest.raises(ValueError, match="Unable to avoid copy while creating"):
+    msg = "Starting on NumPy 2.0, the behavior of the 'copy' keyword has changed "
+    "and passing 'copy=False' raises an error when a zero-copy NumPy array "
+    "is not possible, Pandas will follow this behavior starting with "
+    "version 3.0. This conversion to NumPy requires a copy, but "
+    "'copy=False' was passed. Consider using 'np.asarray(..)' instead."
+    with tm.assert_produces_warning(FutureWarning, match=msg):
         np.array(arr, copy=False)
 
     # except when there are actually no sparse filled values

pandas/tests/base/test_conversion.py

@@ -380,8 +380,12 @@ def test_to_numpy(arr, expected, zero_copy, index_or_series_or_array):
         return
 
     if not zero_copy:
-        with pytest.raises(ValueError, match="Unable to avoid copy while creating"):
-            # An error is always acceptable for `copy=False`
+        msg = "Starting on NumPy 2.0, the behavior of the 'copy' keyword has changed "
+        "and passing 'copy=False' raises an error when a zero-copy NumPy array "
+        "is not possible, Pandas will follow this behavior starting with "
+        "version 3.0. This conversion to NumPy requires a copy, but "
+        "'copy=False' was passed. Consider using 'np.asarray(..)' instead."
+        with tm.assert_produces_warning(FutureWarning, match=msg):
             np.array(thing, copy=False)
 
     else:

pandas/tests/extension/base/interface.py

@@ -82,11 +82,13 @@ def test_array_interface_copy(self, data):
             # copy=False semantics are only supported in NumPy>=2.
             return
 
-        try:
+        msg = "Starting on NumPy 2.0, the behavior of the 'copy' keyword has changed "
+        "and passing 'copy=False' raises an error when a zero-copy NumPy array "
+        "is not possible, Pandas will follow this behavior starting with "
+        "version 3.0. This conversion to NumPy requires a copy, but "
+        "'copy=False' was passed. Consider using 'np.asarray(..)' instead."
+        with tm.assert_produces_warning(FutureWarning, match=msg):
             result_nocopy1 = np.array(data, copy=False)
-        except ValueError:
-            # An error is always acceptable for `copy=False`
-            return
 
         result_nocopy2 = np.array(data, copy=False)
         # If copy=False was given and did not raise, these must share the same data

pandas/tests/extension/json/array.py

@@ -25,9 +25,12 @@
     TYPE_CHECKING,
     Any,
 )
+import warnings
 
 import numpy as np
 
+from pandas.util._exceptions import find_stack_level
+
 from pandas.core.dtypes.cast import construct_1d_object_array_from_listlike
 from pandas.core.dtypes.common import (
     is_bool_dtype,
@@ -148,8 +151,14 @@ def __ne__(self, other):
 
     def __array__(self, dtype=None, copy=None):
         if copy is False:
-            raise ValueError(
-                "Unable to avoid copy while creating an array as requested."
+            warnings.warn(
+                "Starting on NumPy 2.0, the behavior of the 'copy' keyword has changed "
+                "and passing 'copy=False' raises an error when a zero-copy NumPy array "
+                "is not possible, Pandas will follow this behavior starting with "
+                "version 3.0. This conversion to NumPy requires a copy, but "
+                "'copy=False' was passed. Consider using 'np.asarray(..)' instead.",
+                FutureWarning,
+                stacklevel=find_stack_level(),
             )
 
         if dtype is None:

pandas/tests/indexes/multi/test_conversion.py

@@ -47,7 +47,12 @@ def test_array_interface(idx):
         return
 
     # for MultiIndex, copy=False is never allowed
-    with pytest.raises(ValueError, match="Unable to avoid copy while creating"):
+    msg = "Starting on NumPy 2.0, the behavior of the 'copy' keyword has changed "
+    "and passing 'copy=False' raises an error when a zero-copy NumPy array "
+    "is not possible, Pandas will follow this behavior starting with "
+    "version 3.0. This conversion to NumPy requires a copy, but "
+    "'copy=False' was passed. Consider using 'np.asarray(..)' instead."
+    with tm.assert_produces_warning(FutureWarning, match=msg):
         np.array(idx, copy=False)