feat: add generic try_import(module_name, load=True) helper

Author: ghostiee-11

lumen/tests/sources/test_optional_imports.py

@@ -14,7 +14,7 @@
 
 import pytest
 
-from lumen.util import try_import_xarray
+from lumen.util import try_import, try_import_xarray
 
 # Each entry: (module_path, class_name, guard_package, pip_extra)
 OPTIONAL_SOURCES = [
@@ -88,6 +88,29 @@ def mock_import(name, *args, **kwargs):
         sys.modules.update(saved)
 
 
+def test_try_import_returns_module_when_installed():
+    """try_import returns the module object for an importable module."""
+    import pandas
+    assert try_import("pandas") is pandas
+
+
+def test_try_import_returns_none_when_missing():
+    """try_import returns None (not raises) for a module that cannot be imported."""
+    assert try_import("a_module_that_does_not_exist_xyz") is None
+
+
+def test_try_import_load_false_returns_already_imported_module():
+    """try_import(load=False) returns a module that is already imported."""
+    import json
+    assert try_import("json", load=False) is json
+
+
+def test_try_import_load_false_never_imports():
+    """try_import(load=False) must not trigger an import, only consult sys.modules."""
+    with patch("lumen.util.importlib.import_module", side_effect=AssertionError("imported")):
+        assert try_import("a_module_that_does_not_exist_xyz", load=False) is None
+
+
 def test_try_import_xarray_returns_module_when_installed():
     """try_import_xarray returns the xarray module when xarray and xarray-sql are installed."""
     xr = pytest.importorskip("xarray")

lumen/util.py

@@ -493,6 +493,22 @@ def normalize_table_name(name: str) -> str:
     return re.sub(r'\W+', '_', name).strip('_').lower()
 
 
+def try_import(module_name, load=True):
+    """Import and return a module, or None if it is unavailable.
+
+    With load=False the module is returned only if it has already been
+    imported, a cheap check that never triggers an import; this lets a hot path
+    ask whether an optional dependency is in play without paying to import it.
+    With load=True (the default) the module is imported on demand.
+    """
+    if not load:
+        return sys.modules.get(module_name)
+    try:
+        return importlib.import_module(module_name)
+    except ImportError:
+        return None
+
+
 def try_import_xarray():
     """Import and return xarray, or None if xarray or xarray-sql is unavailable."""
     try: