Deprecate dpnp.asfarray() and raise a DeprecationWarning (#2650)

This PR marks `dpnp.asfarray()` as deprecated to align with NumPy>=2.0
where this function was removed ([Release Notes Numpy
2.0](https://numpy.org/doc/2.0/release/2.0.0-notes.html))

A `DeprecationWarning` is now raised informing users that the function
will be removed in a future release and suggesting to use
`dpnp.asarray(dtype=...)` instead.

Author: vlad-perevezentsev

CHANGELOG.md

@@ -31,6 +31,8 @@ Also, that release drops support for Python 3.9, making Python 3.10 the minimum
 
 ### Deprecated
 
+* `dpnp.asfarray` is deprecated. Use `dpnp.asarray` with an appropriate dtype instead [#2650](https://github.com/IntelPython/dpnp/pull/2650)
+
 ### Removed
 
 * Dropped support for Python 3.9 [#2626](https://github.com/IntelPython/dpnp/pull/2626)

doc/reference/_deprecated.rst

@@ -0,0 +1,14 @@
+:orphan:
+
+.. This page is to generate documentation for deprecated APIs removed from the
+   public table of contents.
+
+NumPy Routines
+--------------
+
+.. autosummary::
+   :toctree: generated/
+   :nosignatures:
+
+   # Removed in NumPy v2.0
+   dpnp.asfarray

doc/reference/array-manipulation.rst

@@ -74,7 +74,6 @@ Changing kind of array
    asarray
    asanyarray
    asnumpy
-   asfarray
    asfortranarray
    ascontiguousarray
    asarray_chkfinite

dpnp/dpnp_iface_arraycreation.py

@@ -511,7 +511,6 @@ def asanyarray(
     --------
     :obj:`dpnp.asarray` : Similar function which always returns ndarrays.
     :obj:`dpnp.ascontiguousarray` : Convert input to a contiguous array.
-    :obj:`dpnp.asfarray` : Convert input to a floating point ndarray.
     :obj:`dpnp.asfortranarray` : Convert input to an ndarray with column-major
                                  memory order.
     :obj:`dpnp.asarray_chkfinite` : Similar function which checks input
@@ -624,8 +623,7 @@ def asarray(
     --------
     :obj:`dpnp.asanyarray` : Similar function which passes through subclasses.
     :obj:`dpnp.ascontiguousarray` : Convert input to a contiguous array.
-    :obj:`dpnp.asfarray` : Convert input to a floating point ndarray.
-    :obj:`dpnp.asfortranarray` : Convert input to an ndarray with column-major
+    :obj:`dpnp.asfortranarray` : Convert input to an ndarray with column-majors
                                  memory order.
     :obj:`dpnp.asarray_chkfinite` : Similar function which checks input
                                     for NaNs and Infs.

dpnp/dpnp_iface_manipulation.py

@@ -894,6 +894,11 @@ def asfarray(a, dtype=None, *, device=None, usm_type=None, sycl_queue=None):
     out : dpnp.ndarray
         The input `a` as a float ndarray.
 
+    Warning
+    -------
+    This function is deprecated in favor of :obj:`dpnp.asarray` and
+    will be removed in a future release.
+
     Examples
     --------
     >>> import dpnp as np
@@ -906,6 +911,14 @@ def asfarray(a, dtype=None, *, device=None, usm_type=None, sycl_queue=None):
 
     """
 
+    warnings.warn(
+        "`dpnp.asfarray` is deprecated, "
+        "and will be removed in a future release. "
+        "Please use `dpnp.asarray` with an appropriate dtype instead.",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+
     _sycl_queue = dpnp.get_normalized_queue_device(
         a, sycl_queue=sycl_queue, device=device
     )

dpnp/tests/test_arraymanipulation.py

@@ -1,3 +1,5 @@
+import warnings
+
 import dpctl.tensor as dpt
 import numpy
 import pytest
@@ -31,14 +33,15 @@ def test_asfarray2(self, dtype, data, data_dtype):
         result = dpnp.asfarray(dpnp.array(data, dtype=data_dtype), dtype)
         assert_array_equal(result, expected)
 
-    # This is only for coverage with NumPy 2.0 and above
-    def test_asfarray_coverage(self):
+    def test_asfarray_deprecated(self):
         expected = dpnp.array([1.0, 2.0, 3.0])
-        result = dpnp.asfarray([1, 2, 3])
+        with pytest.warns(DeprecationWarning, match="deprecated"):
+            result = dpnp.asfarray([1, 2, 3])
         assert_array_equal(result, expected)
 
         expected = dpnp.array([1.0, 2.0, 3.0], dtype=dpnp.float32)
-        result = dpnp.asfarray([1, 2, 3], dtype=dpnp.float32)
+        with pytest.warns(DeprecationWarning, match="deprecated"):
+            result = dpnp.asfarray([1, 2, 3], dtype=dpnp.float32)
         assert_array_equal(result, expected)