fix: improve error message when DPC++ backend (libonedal_dpc.so) fails to load (#2998)

* fix: improve error message when DPC++ backend fails to load

When libonedal_dpc.so is missing (e.g. CPU-only oneDAL package split),
the ImportError was silently swallowed and users received a cryptic
internal message when attempting SYCL/queue-based inference:

    RuntimeError: Operations using queues require the DPC/SPMD backend

This change:
1. Captures the ImportError reason in _dpc_load_error at module load time
2. Surfaces a user-actionable error message with the actual load failure
   and install instructions when a SYCL queue is used without DPC++ support

Example new message:
    RuntimeError: oneDAL GPU/DPC++ support is not available in the
    current installation.
      Reason: libonedal_dpc.so.3: cannot open shared object file: ...
      To enable SYCL/GPU acceleration, install the GPU extras:
        pip install scikit-learn-intelex[gpu]
      or via conda:
        conda install -c https://software.repos.intel.com/python/conda scikit-learn-intelex

* fix: wrap long string to satisfy flake8 E501 (max-line-length=90)

* fix: use scikit-learn-intelex-gpu in conda install hint

* docs: note Polars DataFrame support in supported input types

* fix: refactor DPC++ load error into throw_if_no_dpc_available()

Addresses david-cortes-intel review comments on #2998:

- Add _spmd_load_error captured from SPMD backend ImportError
- Replace _dpc_load_error inline check with throw_if_no_dpc_available(require_spmd)
  which handles both DPC++ and SPMD backends uniformly
- Function raises actionable error with reason + install instructions
  only when the backend actually failed to load (avoids misleading message
  when file exists but import fails for other reasons like SYCL runtime)
- Use require_spmd=self.backend.is_spmd so SPMD-only backends surface
  the correct error message

* lint: fix docstring style for throw_if_no_dpc_available

* fix: rename to _ensure_dpc_available, always raise when backend is None, remove dead raise

- Rename throw_if_no_dpc_available -> _ensure_dpc_available (Pythonic convention)
- Change gate from 'if error_msg' to 'if backend is None' so the function
  always raises with install instructions, even when the package was never
  installed (no ImportError captured). The Reason line is only included when
  an ImportError message is available.
- Remove the dead 'raise RuntimeError("Operations using...")' fallthrough in
  _backend.py — _ensure_dpc_available unconditionally raises when backend is None
- Remove private _dpc_load_error/_spmd_load_error from __all__; only expose
  the public helper function
- Add Notes section to docstring documenting import-time capture semantics

Addresses david-cortes-intel review comments.

* revert: remove Polars line from input-types.rst (out of scope for this PR)

* Update onedal/__init__.py

Co-authored-by: david-cortes-intel <david.cortes@intel.com>

* fix: only capture ImportError reason when .so file is present

When the DPC++/SPMD backend package is simply not installed,
ImportError gives 'No module named onedal._onedal_py_dpc' which
is not actionable. Only populate _dpc_load_error/_spmd_load_error
when the .so file actually exists in the package directory — meaning
the library is present but failed to load (e.g. missing SYCL runtime,
incompatible libsycl.so). Uses pathlib.glob() at module init time.

Addresses david-cortes-intel review comment.

* refactor: reuse backend binary presence check for Windows and load diagnostics

---------

Co-authored-by: david-cortes-intel <david.cortes@intel.com>

Author: napetrov

onedal/__init__.py

@@ -15,6 +15,7 @@
 # limitations under the License.
 # ==============================================================================
 
+import pathlib as _pathlib
 import platform
 
 from daal4py.sklearn._utils import daal_check_version
@@ -61,9 +62,13 @@ def __repr__(self) -> str:
         return f"Backend({self.backend}, is_dpc={self.is_dpc}, is_spmd={self.is_spmd})"
 
 
+def _backend_binary_present(prefix: str) -> bool:
+    """Return True if a backend extension binary with the given prefix exists."""
+    return any(_pathlib.Path(__file__).parent.glob(f"{prefix}*"))
+
+
 if "Windows" in platform.system():
     import os
-    import pathlib
     import site
     import sys
 
@@ -78,12 +83,7 @@ def __repr__(self) -> str:
             if os.path.exists(dal_root_redist):
                 os.add_dll_directory(dal_root_redist)
 
-        has_dpc_file = False
-        for file_name in os.listdir(pathlib.Path(__file__).parent):
-            if file_name.startswith("_onedal_py_dpc"):
-                has_dpc_file = True
-                break
-        if has_dpc_file:
+        if _backend_binary_present("_onedal_py_dpc"):
             for dep_root in ["CMPLR_ROOT", "MKLROOT"]:
                 if dep_root in os.environ:
                     dep_root_dir = os.path.join(os.environ[dep_root], "bin")
@@ -97,16 +97,30 @@ def __repr__(self) -> str:
     os.environ["PATH"] = path_to_libs + os.pathsep + os.environ["PATH"]
 
 
+# Preserved ImportError messages when DPC++/SPMD backends fail to load.
+# Used by _ensure_dpc_available() to surface actionable error messages.
+# Only populated when the backend .so file exists but fails to import
+# (e.g. missing SYCL runtime). Stays empty when the package is simply
+# not installed — in that case "No module named X" is not informative.
+_dpc_load_error: str = ""
+_spmd_load_error: str = ""
+
+_dpc_file_present = _backend_binary_present("_onedal_py_dpc")
+_spmd_file_present = _backend_binary_present("_onedal_py_spmd_dpc")
+
 try:
     # use dpc backend if available
     import onedal._onedal_py_dpc
 
     _dpc_backend = Backend(onedal._onedal_py_dpc, is_dpc=True, is_spmd=False)
 
     _host_backend = None
-except ImportError:
-    # fall back to host backend
+except ImportError as _dpc_import_err:
+    # fall back to host backend; preserve reason only when the .so exists
+    # (file-not-found ImportError is not actionable for end users)
     _dpc_backend = None
+    if _dpc_file_present:
+        _dpc_load_error = str(_dpc_import_err)
 
     import onedal._onedal_py_host
 
@@ -117,8 +131,10 @@ def __repr__(self) -> str:
     import onedal._onedal_py_spmd_dpc
 
     _spmd_backend = Backend(onedal._onedal_py_spmd_dpc, is_dpc=True, is_spmd=True)
-except ImportError:
+except ImportError as _spmd_import_err:
     _spmd_backend = None
+    if _spmd_file_present:
+        _spmd_load_error = str(_spmd_import_err)
 
 # if/elif/else layout required for pylint to realize _default_backend cannot be None
 if _dpc_backend is not None:
@@ -128,8 +144,53 @@ def __repr__(self) -> str:
 else:
     raise ImportError("No oneDAL backend available")
 
+
+def _ensure_dpc_available(require_spmd: bool = False) -> None:
+    """Raise a user-actionable RuntimeError if the required DPC++/SPMD backend is unavailable.
+
+    This function should be called when a SYCL queue is present but the
+    corresponding backend was not loaded. It always raises when the backend
+    is ``None`` (whether due to a load error or because the package was never
+    installed), and includes the original ``ImportError`` reason when available.
+
+    Parameters
+    ----------
+    require_spmd : bool, default=False
+        If True, check the SPMD backend; otherwise check the DPC++ backend.
+
+    Raises
+    ------
+    RuntimeError
+        Always raised when the requested backend is unavailable.
+        Includes the original ImportError reason (if captured) and
+        install instructions.
+
+    Notes
+    -----
+    Backend availability is determined at module import time. If the GPU
+    package is installed after the interpreter has started, Python must be
+    restarted for the change to take effect.
+    """
+    backend = _spmd_backend if require_spmd else _dpc_backend
+    if backend is not None:
+        return  # backend is available, nothing to do
+    error_msg = _spmd_load_error if require_spmd else _dpc_load_error
+    backend_label = "SPMD" if require_spmd else "DPC++"
+    reason = f"\n  Reason: {error_msg}" if error_msg else ""
+    raise RuntimeError(
+        f"oneDAL GPU/{backend_label} support is not available "
+        f"in the current installation.{reason}\n"
+        "  To enable SYCL/GPU acceleration, install the GPU extras:\n"
+        "    pip install scikit-learn-intelex-gpu\n"
+        "  or via conda:\n"
+        "    conda install scikit-learn-intelex-gpu -c "
+        "https://software.repos.intel.com/python/conda"
+    )
+
+
 # Core modules to export
 __all__ = [
+    "_ensure_dpc_available",
     "_host_backend",
     "_default_backend",
     "_dpc_backend",

onedal/common/_backend.py

@@ -116,7 +116,12 @@ def __call__(self, *args: Any, **kwargs: Any) -> Any:
         queue = QM.get_global_queue()
 
         if queue is not None and not (self.backend.is_dpc or self.backend.is_spmd):
-            raise RuntimeError("Operations using queues require the DPC/SPMD backend")
+            from onedal import _ensure_dpc_available
+
+            # Always raises with install instructions (and ImportError reason if
+            # available). The old generic raise is removed — _ensure_dpc_available
+            # unconditionally raises when the backend is None.
+            _ensure_dpc_available(require_spmd=self.backend.is_spmd)
 
         if self.backend.is_spmd and queue is None:
             raise RuntimeError("Executing functions from SPMD backend requires a queue")