Add dpnp.exceptions submodule to aggregate generic exceptions (#2616)

The PR adds `dpnp.exceptions` submodule to aggregate generic exceptions
used by dpnp.
Also it implements a dedicated documentation page for them

Author: antonwolfy

.gitignore

@@ -7,6 +7,11 @@ dpnp.egg-info
 # Byte-compiled / optimized / DLL files
 __pycache__/
 
+# Doc build and generated files
+doc/_build/
+doc/reference/generated/
+doc/reference/*.inc
+
 # Code project files
 .vscode
 

CHANGELOG.md

@@ -12,6 +12,7 @@ This release changes the license from `BSD-2-Clause` to `BSD-3-Clause`.
 
 * Added the docstrings to `dpnp.linalg.LinAlgError` exception [#2613](https://github.com/IntelPython/dpnp/pull/2613)
 * Added implementation of `dpnp.linalg.lu_solve` for batch inputs (SciPy-compatible) [#2619](https://github.com/IntelPython/dpnp/pull/2619)
+* Added `dpnp.exceptions` submodule to aggregate the generic exceptions used by dpnp [#2616](https://github.com/IntelPython/dpnp/pull/2616)
 
 ### Changed
 

doc/reference/exceptions.rst

@@ -0,0 +1,71 @@
+.. _routines.exceptions:
+
+.. py:module:: dpnp.exceptions
+
+Exceptions and Warnings
+=======================
+
+General exceptions used by DPNP. Note that some exceptions may be module
+specific, such as linear algebra errors.
+
+Exceptions
+----------
+
+.. exception:: AxisError
+
+   Given when an axis is invalid.
+
+.. exception:: DLPackCreationError
+
+   Given when constructing DLPack capsule from either :class:`dpnp.ndarray` or
+   :class:`dpctl.tensor.usm_ndarray` based on a USM allocation
+   on a partitioned SYCL device.
+
+   .. rubric:: Examples
+
+   .. code-block:: python
+
+      >>> import dpnp as np
+      >>> import dpctl
+      >>> dev = dpctl.SyclDevice('cpu')
+      >>> sdevs = dev.create_sub_devices(partition=[1, 1])
+      >>> q = dpctl.SyclQueue(sdevs[0])
+      >>> x = np.ones(10, sycl_queue=q)
+      >>> np.from_dlpack(x)
+      Traceback (most recent call last):
+      ...
+      DLPackCreationError: to_dlpack_capsule: DLPack can only export arrays based on USM allocations bound to a default platform SYCL context
+
+.. exception:: ExecutionPlacementError
+
+   Given when execution placement target can not be unambiguously determined
+   from input arrays. Make sure that input arrays are associated with the same
+   :class:`dpctl.SyclQueue`, or migrate data to the same
+   :class:`dpctl.SyclQueue` using :meth:`dpnp.ndarray.to_device` method.
+
+.. exception:: SyclContextCreationError
+
+   Given when :class:`dpctl.SyclContext` instance could not be created.
+
+.. exception:: SyclDeviceCreationError
+
+   Given when :class:`dpctl.SyclDevice` instance could not be created.
+
+.. exception:: SyclQueueCreationError
+
+   Given when :class:`dpctl.SyclQueue` instance could not be created.
+   The creation can fail if the filter string is invalid, or the backend or
+   device type values are not supported.
+
+.. exception:: USMAllocationError
+
+   Given when Unified Shared Memory (USM) allocation call returns a null
+   pointer, signaling a failure to perform the allocation.
+   Some common reasons for allocation failure are:
+
+      * insufficient free memory to perform the allocation request
+      * allocation size exceeds the maximum supported by targeted backend
+
+
+.. automodule:: dpnp.exceptions
+    :no-index:

doc/reference/routines.rst

@@ -15,6 +15,7 @@ These functions cover a subset of
    array-manipulation
    bitwise
    dtype
+   exceptions
    fft
    functional
    indexing

dpnp/__init__.py

@@ -73,14 +73,15 @@
 from .dpnp_iface_utils import *
 from .dpnp_iface_utils import __all__ as _ifaceutils__all__
 from ._version import get_versions
+from . import exceptions as exceptions
 from . import linalg as linalg
 from . import scipy as scipy
 
 __all__ = _iface__all__
 __all__ += _ifaceutils__all__
 
 # add submodules
-__all__ += ["linalg", "scipy"]
+__all__ += ["exceptions", "linalg", "scipy"]
 
 
 __version__ = get_versions()["version"]

dpnp/dpnp_iface_arraycreation.py

@@ -2234,9 +2234,12 @@ def from_dlpack(x, /, *, device=None, copy=None):
     Raises
     ------
     TypeError
-        if `obj` does not implement ``__dlpack__`` method
+        If `x` does not implement ``__dlpack__`` method.
     ValueError
-        if data of the input object resides on an unsupported device
+        If data of the input object resides on an unsupported device.
+    DLPackCreationError
+        When `x` is allocated on a partitioned SYCL device, or with
+        a non-default context.
 
     Notes
     -----

dpnp/exceptions/__init__.py

@@ -0,0 +1,48 @@
+# -*- coding: utf-8 -*-
+# *****************************************************************************
+# Copyright (c) 2025, Intel Corporation
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+# - Redistributions of source code must retain the above copyright notice,
+#   this list of conditions and the following disclaimer.
+# - Redistributions in binary form must reproduce the above copyright notice,
+#   this list of conditions and the following disclaimer in the documentation
+#   and/or other materials provided with the distribution.
+# - Neither the name of the copyright holder nor the names of its contributors
+#   may be used to endorse or promote products derived from this software
+#   without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
+# THE POSSIBILITY OF SUCH DAMAGE.
+# *****************************************************************************
+
+from dpctl import (
+    SyclContextCreationError,
+    SyclDeviceCreationError,
+    SyclQueueCreationError,
+)
+from dpctl.memory import USMAllocationError
+from dpctl.tensor._dlpack import DLPackCreationError
+from dpctl.utils import ExecutionPlacementError
+from numpy.exceptions import AxisError
+
+__all__ = [
+    "AxisError",
+    "DLPackCreationError",
+    "ExecutionPlacementError",
+    "SyclDeviceCreationError",
+    "SyclContextCreationError",
+    "SyclQueueCreationError",
+    "USMAllocationError",
+]

setup.py

@@ -36,6 +36,7 @@
         "dpnp",
         "dpnp.dpnp_algo",
         "dpnp.dpnp_utils",
+        "dpnp.exceptions",
         "dpnp.fft",
         "dpnp.linalg",
         "dpnp.memory",