MAINT: make np._from_dlpack public

11 files changed, 51 insertions, 30 deletions

diff --git a/doc/neps/nep-0047-array-api-standard.rst b/doc/neps/nep-0047-array-api-standard.rst
index 53b8e35b0..a94b3b423 100644
--- a/doc/neps/nep-0047-array-api-standard.rst
+++ b/doc/neps/nep-0047-array-api-standard.rst
@@ -340,7 +340,7 @@ Adding support for DLPack to NumPy entails:
 
 - Adding a ``ndarray.__dlpack__()`` method which returns a ``dlpack`` C
   structure wrapped in a ``PyCapsule``.
-- Adding a ``np._from_dlpack(obj)`` function, where ``obj`` supports
+- Adding a ``np.from_dlpack(obj)`` function, where ``obj`` supports
   ``__dlpack__()``, and returns an ``ndarray``.
 
 DLPack is currently a ~200 LoC header, and is meant to be included directly, so
diff --git a/doc/source/reference/routines.array-creation.rst b/doc/source/reference/routines.array-creation.rst
index 30780c286..9d2954f2c 100644
--- a/doc/source/reference/routines.array-creation.rst
+++ b/doc/source/reference/routines.array-creation.rst
@@ -35,6 +35,7 @@ From existing data
    asmatrix
    copy
    frombuffer
+   from_dlpack
    fromfile
    fromfunction
    fromiter
diff --git a/numpy/__init__.pyi b/numpy/__init__.pyi
index 297c482e5..59a0c6673 100644
--- a/numpy/__init__.pyi
+++ b/numpy/__init__.pyi
@@ -4372,4 +4372,4 @@ class chararray(ndarray[_ShapeType, _CharDType]):
 class _SupportsDLPack(Protocol[_T_contra]):
     def __dlpack__(self, *, stream: None | _T_contra = ...) -> _PyCapsule: ...
 
-def _from_dlpack(__obj: _SupportsDLPack[None]) -> NDArray[Any]: ...
+def from_dlpack(__obj: _SupportsDLPack[None]) -> NDArray[Any]: ...
diff --git a/numpy/array_api/_creation_functions.py b/numpy/array_api/_creation_functions.py
index 741498ff6..3b014d37b 100644
--- a/numpy/array_api/_creation_functions.py
+++ b/numpy/array_api/_creation_functions.py
@@ -154,7 +154,7 @@ def eye(
 def from_dlpack(x: object, /) -> Array:
     from ._array_object import Array
 
-    return Array._new(np._from_dlpack(x))
+    return Array._new(np.from_dlpack(x))
 
 
 def full(
diff --git a/numpy/core/_add_newdocs.py b/numpy/core/_add_newdocs.py
index 6ac9951fb..e31b7671c 100644
--- a/numpy/core/_add_newdocs.py
+++ b/numpy/core/_add_newdocs.py
@@ -1573,17 +1573,37 @@ add_newdoc('numpy.core.multiarray', 'frombuffer',
         array_function_like_doc,
     ))
 
-add_newdoc('numpy.core.multiarray', '_from_dlpack',
+add_newdoc('numpy.core.multiarray', 'from_dlpack',
     """
-    _from_dlpack(x, /)
+    from_dlpack(x, /)
 
     Create a NumPy array from an object implementing the ``__dlpack__``
-    protocol.
+    protocol. Generally, the returned NumPy array is a read-only view
+    of the input object. See [1]_ and [2]_ for more details.
 
-    See Also
+    Parameters
+    ----------
+    x : object
+        A Python object that implements the ``__dlpack__`` method.
+
+    Returns
+    -------
+    out : ndarray
+
+    References
+    ----------
+    .. [1] Array API documentation,
+       https://data-apis.org/array-api/latest/design_topics/data_interchange.html#syntax-for-data-interchange-with-dlpack
+
+    .. [2] Python specification for DLPack,
+       https://dmlc.github.io/dlpack/latest/python_spec.html
+
+    Examples
     --------
-    `Array API documentation
-    <https://data-apis.org/array-api/latest/design_topics/data_interchange.html#syntax-for-data-interchange-with-dlpack>`_
+    >>> import torch
+    >>> x = torch.arange(10)
+    >>> # create a view of the torch tensor "x" in NumPy
+    >>> y = np.from_dlpack(x)
     """)
 
 add_newdoc('numpy.core', 'fastCopyAndTranspose',
diff --git a/numpy/core/multiarray.py b/numpy/core/multiarray.py
index f88d75978..1a37ed3e1 100644
--- a/numpy/core/multiarray.py
+++ b/numpy/core/multiarray.py
@@ -14,7 +14,7 @@ from ._multiarray_umath import *  # noqa: F403
 # do not change them. issue gh-15518
 # _get_ndarray_c_version is semi-public, on purpose not added to __all__
 from ._multiarray_umath import (
-    _fastCopyAndTranspose, _flagdict, _from_dlpack, _insert, _reconstruct,
+    _fastCopyAndTranspose, _flagdict, from_dlpack, _insert, _reconstruct,
     _vec_string, _ARRAY_API, _monotonicity, _get_ndarray_c_version,
     _set_madvise_hugepage,
     )
@@ -24,7 +24,7 @@ __all__ = [
     'ITEM_HASOBJECT', 'ITEM_IS_POINTER', 'LIST_PICKLE', 'MAXDIMS',
     'MAY_SHARE_BOUNDS', 'MAY_SHARE_EXACT', 'NEEDS_INIT', 'NEEDS_PYAPI',
     'RAISE', 'USE_GETITEM', 'USE_SETITEM', 'WRAP', '_fastCopyAndTranspose',
-    '_flagdict', '_from_dlpack', '_insert', '_reconstruct', '_vec_string',
+    '_flagdict', 'from_dlpack', '_insert', '_reconstruct', '_vec_string',
     '_monotonicity', 'add_docstring', 'arange', 'array', 'asarray',
     'asanyarray', 'ascontiguousarray', 'asfortranarray', 'bincount',
     'broadcast', 'busday_count', 'busday_offset', 'busdaycalendar', 'can_cast',
@@ -47,7 +47,7 @@ _reconstruct.__module__ = 'numpy.core.multiarray'
 scalar.__module__ = 'numpy.core.multiarray'
 
 
-_from_dlpack.__module__ = 'numpy'
+from_dlpack.__module__ = 'numpy'
 arange.__module__ = 'numpy'
 array.__module__ = 'numpy'
 asarray.__module__ = 'numpy'
diff --git a/numpy/core/numeric.py b/numpy/core/numeric.py
index 2c5265709..fa5e9c67c 100644
--- a/numpy/core/numeric.py
+++ b/numpy/core/numeric.py
@@ -13,7 +13,7 @@ from .multiarray import (
     WRAP, arange, array, asarray, asanyarray, ascontiguousarray,
     asfortranarray, broadcast, can_cast, compare_chararrays,
     concatenate, copyto, dot, dtype, empty,
-    empty_like, flatiter, frombuffer, _from_dlpack, fromfile, fromiter,
+    empty_like, flatiter, frombuffer, from_dlpack, fromfile, fromiter,
     fromstring, inner, lexsort, matmul, may_share_memory,
     min_scalar_type, ndarray, nditer, nested_iters, promote_types,
     putmask, result_type, set_numeric_ops, shares_memory, vdot, where,
@@ -41,7 +41,7 @@ __all__ = [
     'newaxis', 'ndarray', 'flatiter', 'nditer', 'nested_iters', 'ufunc',
     'arange', 'array', 'asarray', 'asanyarray', 'ascontiguousarray',
     'asfortranarray', 'zeros', 'count_nonzero', 'empty', 'broadcast', 'dtype',
-    'fromstring', 'fromfile', 'frombuffer', '_from_dlpack', 'where',
+    'fromstring', 'fromfile', 'frombuffer', 'from_dlpack', 'where',
     'argwhere', 'copyto', 'concatenate', 'fastCopyAndTranspose', 'lexsort',
     'set_numeric_ops', 'can_cast', 'promote_types', 'min_scalar_type',
     'result_type', 'isfortran', 'empty_like', 'zeros_like', 'ones_like',
diff --git a/numpy/core/src/common/npy_dlpack.h b/numpy/core/src/common/npy_dlpack.h
index 14ca352c0..cb926a262 100644
--- a/numpy/core/src/common/npy_dlpack.h
+++ b/numpy/core/src/common/npy_dlpack.h
@@ -23,6 +23,6 @@ array_dlpack_device(PyArrayObject *self, PyObject *NPY_UNUSED(args));
 
 
 NPY_NO_EXPORT PyObject *
-_from_dlpack(PyObject *NPY_UNUSED(self), PyObject *obj);
+from_dlpack(PyObject *NPY_UNUSED(self), PyObject *obj);
 
 #endif
diff --git a/numpy/core/src/multiarray/dlpack.c b/numpy/core/src/multiarray/dlpack.c
index e4886cf4b..d5b1af101 100644
--- a/numpy/core/src/multiarray/dlpack.c
+++ b/numpy/core/src/multiarray/dlpack.c
@@ -269,7 +269,7 @@ array_dlpack_device(PyArrayObject *self, PyObject *NPY_UNUSED(args))
 }
 
 NPY_NO_EXPORT PyObject *
-_from_dlpack(PyObject *NPY_UNUSED(self), PyObject *obj) {
+from_dlpack(PyObject *NPY_UNUSED(self), PyObject *obj) {
     PyObject *capsule = PyObject_CallMethod((PyObject *)obj->ob_type,
             "__dlpack__", "O", obj);
     if (capsule == NULL) {
diff --git a/numpy/core/src/multiarray/multiarraymodule.c b/numpy/core/src/multiarray/multiarraymodule.c
index 12923a6c6..f206ce2c6 100644
--- a/numpy/core/src/multiarray/multiarraymodule.c
+++ b/numpy/core/src/multiarray/multiarraymodule.c
@@ -4485,7 +4485,7 @@ static struct PyMethodDef array_module_methods[] = {
     {"_reload_guard", (PyCFunction)_reload_guard,
         METH_NOARGS,
         "Give a warning on reload and big warning in sub-interpreters."},
-    {"_from_dlpack", (PyCFunction)_from_dlpack,
+    {"from_dlpack", (PyCFunction)from_dlpack,
         METH_O, NULL},
     {NULL, NULL, 0, NULL}                /* sentinel */
 };
diff --git a/numpy/core/tests/test_dlpack.py b/numpy/core/tests/test_dlpack.py
index 43a663f66..54cc365ca 100644
--- a/numpy/core/tests/test_dlpack.py
+++ b/numpy/core/tests/test_dlpack.py
@@ -27,12 +27,12 @@ class TestDLPack:
         z = y['int']
 
         with pytest.raises(RuntimeError):
-            np._from_dlpack(z)
+            np.from_dlpack(z)
 
     @pytest.mark.skipif(IS_PYPY, reason="PyPy can't get refcounts.")
     def test_from_dlpack_refcount(self):
         x = np.arange(5)
-        y = np._from_dlpack(x)
+        y = np.from_dlpack(x)
         assert sys.getrefcount(x) == 3
         del y
         assert sys.getrefcount(x) == 2
@@ -45,7 +45,7 @@ class TestDLPack:
     ])
     def test_dtype_passthrough(self, dtype):
         x = np.arange(5, dtype=dtype)
-        y = np._from_dlpack(x)
+        y = np.from_dlpack(x)
 
         assert y.dtype == x.dtype
         assert_array_equal(x, y)
@@ -54,44 +54,44 @@ class TestDLPack:
         x = np.asarray(np.datetime64('2021-05-27'))
 
         with pytest.raises(TypeError):
-            np._from_dlpack(x)
+            np.from_dlpack(x)
 
     def test_invalid_byte_swapping(self):
         dt = np.dtype('=i8').newbyteorder()
         x = np.arange(5, dtype=dt)
 
         with pytest.raises(TypeError):
-            np._from_dlpack(x)
+            np.from_dlpack(x)
 
     def test_non_contiguous(self):
         x = np.arange(25).reshape((5, 5))
 
         y1 = x[0]
-        assert_array_equal(y1, np._from_dlpack(y1))
+        assert_array_equal(y1, np.from_dlpack(y1))
 
         y2 = x[:, 0]
-        assert_array_equal(y2, np._from_dlpack(y2))
+        assert_array_equal(y2, np.from_dlpack(y2))
 
         y3 = x[1, :]
-        assert_array_equal(y3, np._from_dlpack(y3))
+        assert_array_equal(y3, np.from_dlpack(y3))
 
         y4 = x[1]
-        assert_array_equal(y4, np._from_dlpack(y4))
+        assert_array_equal(y4, np.from_dlpack(y4))
 
         y5 = np.diagonal(x).copy()
-        assert_array_equal(y5, np._from_dlpack(y5))
+        assert_array_equal(y5, np.from_dlpack(y5))
 
     @pytest.mark.parametrize("ndim", range(33))
     def test_higher_dims(self, ndim):
         shape = (1,) * ndim
         x = np.zeros(shape, dtype=np.float64)
 
-        assert shape == np._from_dlpack(x).shape
+        assert shape == np.from_dlpack(x).shape
 
     def test_dlpack_device(self):
         x = np.arange(5)
         assert x.__dlpack_device__() == (1, 0)
-        y = np._from_dlpack(x)
+        y = np.from_dlpack(x)
         assert y.__dlpack_device__() == (1, 0)
         z = y[::2]
         assert z.__dlpack_device__() == (1, 0)
@@ -113,7 +113,7 @@ class TestDLPack:
 
     def test_ndim0(self):
         x = np.array(1.0)
-        y = np._from_dlpack(x)
+        y = np.from_dlpack(x)
         assert_array_equal(x, y)
 
     def test_size1dims_arrays(self):