feat: Add runtime warnings for loader path configuration in embedded mode

Author: grongierisc

README.md

@@ -114,6 +114,9 @@ before Python starts. `iris.connect(path=...)` can configure Python import paths
 at runtime, but it cannot repair Unix dynamic loader resolution after the
 process has already started. If `pythonint` is found but its dependent shared
 libraries are not, the runtime error names the loader-path variable that must
+include the IRIS `bin` directory. When embedded-local is configured through
+`IRISINSTALLDIR`, `ISC_PACKAGE_INSTALLDIR`, or `path=...`, the wrapper also
+emits a `RuntimeWarning` on Unix if that loader-path variable does not already
 include the IRIS `bin` directory.
 
 #### Linux and macOS

_iris_ep/_bootstrap.py

@@ -1,9 +1,11 @@
 import importlib
 import os
 import sys
+import warnings
 
 from iris_utils import update_dynalib_path
 
+_LOADER_PATH_WARNINGS_EMITTED = set()
 _SHARED_LIBRARY_ERROR_MARKERS = (
     "cannot open shared object file",
     "dlopen(",
@@ -35,7 +37,51 @@ def _push_sys_paths_front(paths):
     return original
 
 
-def configure_install_dir(path):
+def _env_path_contains(env_var, path):
+    target = os.path.normcase(os.path.realpath(os.fspath(path)))
+    current_paths = os.environ.get(env_var, "")
+    for entry in current_paths.split(os.pathsep):
+        if not entry:
+            continue
+        candidate = os.path.normcase(os.path.realpath(entry))
+        if candidate == target:
+            return True
+    return False
+
+
+def format_loader_path_warning(install_dir):
+    bin_dir = os.path.join(install_dir, 'bin')
+    env_var = get_loader_path_env_var()
+    return (
+        f"IRIS embedded-local loading may fail because {env_var} does not "
+        f"include {bin_dir}. Set {env_var} to include the IRIS bin directory "
+        f"before Python starts; changing it after startup may be too late for "
+        f"the dynamic loader."
+    )
+
+
+def warn_if_loader_path_unconfigured(install_dir):
+    if sys.platform.startswith('win'):
+        return
+
+    bin_dir = os.path.join(install_dir, 'bin')
+    env_var = get_loader_path_env_var()
+    if _env_path_contains(env_var, bin_dir):
+        return
+
+    warning_key = (env_var, os.path.normcase(os.path.realpath(bin_dir)))
+    if warning_key in _LOADER_PATH_WARNINGS_EMITTED:
+        return
+    _LOADER_PATH_WARNINGS_EMITTED.add(warning_key)
+
+    warnings.warn(
+        format_loader_path_warning(install_dir),
+        RuntimeWarning,
+        stacklevel=3,
+    )
+
+
+def configure_install_dir(path, *, warn_loader_path=False):
     if not path:
         raise ValueError("path must be a non-empty IRIS installation directory")
 
@@ -59,6 +105,9 @@ def configure_install_dir(path):
     _append_sys_path(bin_dir)
     _append_sys_path(python_dir)
 
+    if warn_loader_path:
+        warn_if_loader_path_unconfigured(install_dir)
+
     update_dynalib_path(bin_dir)
     return install_dir
 

_iris_ep/_runtime_facade.py

@@ -235,7 +235,10 @@ def configure_from_environment(self) -> None:
             logging.warning("IRISINSTALLDIR or ISC_PACKAGE_INSTALLDIR environment variable is not set")
             logging.warning("Embedded Python not configured; call iris.connect(path=...) to configure it")
         else:
-            _bootstrap.configure_install_dir(installdir)
+            _bootstrap.configure_install_dir(
+                installdir,
+                warn_loader_path=not _bootstrap.is_embedded_kernel(),
+            )
 
         if _bootstrap.is_embedded_kernel():
             module = _bootstrap.import_embedded_kernel_module()
@@ -348,7 +351,7 @@ def sync_public_modules(self):
                 setattr(module, "__getattr__", self.module_globals["__getattr__"])
 
     def load_embedded_backend(self, path):
-        install_dir = _bootstrap.configure_install_dir(path)
+        install_dir = _bootstrap.configure_install_dir(path, warn_loader_path=True)
         module = _bootstrap.import_pythonint_module_from_install_dir(install_dir)
         self.install_embedded_module(module)
         return self.runtime_manager.configure(mode='embedded', install_dir=install_dir)

docs/index.md

@@ -30,7 +30,10 @@ Set the following environment variables :
 Embedded-local execution from regular `python3` on Unix needs the loader path
 configured before Python starts. `iris.connect(path=...)` can configure Python
 import paths at runtime, but it cannot repair Unix dynamic loader resolution
-after startup.
+after startup. When embedded-local is configured through `IRISINSTALLDIR`,
+`ISC_PACKAGE_INSTALLDIR`, or `path=...`, the wrapper emits a `RuntimeWarning`
+on Unix if the loader-path variable does not already include the IRIS `bin`
+directory.
 
 ### For Linux and MacOS
 

pyproject.toml

@@ -3,7 +3,7 @@ requires = ["setuptools", "wheel"]
 
 [project]
 name = "iris-embedded-python-wrapper"
-version = "0.5.17"
+version = "0.5.18"
 description = "Wrapper for embedded python on InterSystems IRIS"
 readme = "README.md"
 authors = [

tests/iris/test_dbapi_runtime_modes.py

@@ -17,6 +17,9 @@ def _install_fake_embedded_runtime(monkeypatch, tmp_path, fake_statement):
     (install_dir / "bin").mkdir(parents=True)
     (install_dir / "lib" / "python").mkdir(parents=True)
     dynalib_paths = []
+    if not sys.platform.startswith("win"):
+        env_var = _iris_ep._bootstrap.get_loader_path_env_var()
+        monkeypatch.setenv(env_var, str(install_dir / "bin"))
 
     fake_module = types.SimpleNamespace(
         __file__=str(install_dir / "bin" / "pythonint.so"),
@@ -341,6 +344,9 @@ def test_dbapi_connect_path_surfaces_loader_path_import_error(monkeypatch, tmp_p
     install_dir = tmp_path / "iris"
     (install_dir / "bin").mkdir(parents=True)
     (install_dir / "lib" / "python").mkdir(parents=True)
+    if not sys.platform.startswith("win"):
+        env_var = _iris_ep._bootstrap.get_loader_path_env_var()
+        monkeypatch.setenv(env_var, str(install_dir / "bin"))
 
     def fake_import_module(name):
         raise ImportError("libirisdb.so: cannot open shared object file")

tests/iris/test_import_contracts.py

@@ -101,6 +101,38 @@ def tracking_import_module(name, *args, **kwargs):
     assert "NO_PYTHONINT_PROBE_OK" in result.stdout
 
 
+@pytest.mark.skipif(sys.platform.startswith("win"), reason="Unix loader-path warning")
+@pytest.mark.parametrize("install_env", ["IRISINSTALLDIR", "ISC_PACKAGE_INSTALLDIR"])
+def test_import_iris_with_install_env_warns_when_loader_path_wrong(tmp_path, install_env):
+    install_dir = tmp_path / "iris"
+    other_dir = tmp_path / "other"
+    (install_dir / "bin").mkdir(parents=True)
+    (install_dir / "lib" / "python").mkdir(parents=True)
+    other_dir.mkdir()
+    env_var = "DYLD_LIBRARY_PATH" if sys.platform == "darwin" else "LD_LIBRARY_PATH"
+
+    result = _fresh_python(
+        """
+        import warnings
+
+        warnings.simplefilter("always", RuntimeWarning)
+        import iris
+
+        assert iris.runtime.get().install_dir
+        print("INSTALL_ENV_LOADER_WARNING_OK")
+        """,
+        tmp_path,
+        extra_env={
+            install_env: str(install_dir),
+            env_var: str(other_dir),
+        },
+    )
+
+    _assert_fresh_python_ok(result)
+    assert "INSTALL_ENV_LOADER_WARNING_OK" in result.stdout
+    assert f"{env_var} does not include {install_dir / 'bin'}" in result.stderr
+
+
 def test_native_dbapi_import_contract_preserves_wrapper_parent(tmp_path):
     try:
         importlib.metadata.distribution("intersystems-irispython")

tests/iris/test_iris.py

@@ -36,6 +36,13 @@ def _restore_module_attrs(snapshot):
         else:
             setattr(module, name, value)
 
+
+def _set_loader_path(monkeypatch, install_dir):
+    if not sys.platform.startswith("win"):
+        env_var = _iris_ep._bootstrap.get_loader_path_env_var()
+        monkeypatch.setenv(env_var, str(install_dir / "bin"))
+
+
 def test_import_iris():
     import iris
 
@@ -101,6 +108,7 @@ def test_connect_path_enables_embedded_runtime(monkeypatch, tmp_path):
     (install_dir / "bin").mkdir(parents=True)
     (install_dir / "lib" / "python").mkdir(parents=True)
     dynalib_paths = []
+    _set_loader_path(monkeypatch, install_dir)
 
     class FakeVersion:
         @staticmethod
@@ -179,6 +187,7 @@ def test_connect_path_reports_loader_path_import_error(monkeypatch, tmp_path):
     (install_dir / "bin").mkdir(parents=True)
     (install_dir / "lib" / "python").mkdir(parents=True)
     dynalib_paths = []
+    _set_loader_path(monkeypatch, install_dir)
 
     def fake_import_module(name):
         raise ImportError("dlopen(pythonint.so): Library not loaded: libirisdb.dylib")
@@ -196,13 +205,74 @@ def fake_import_module(name):
     iris.runtime.reset()
 
 
+@pytest.mark.skipif(sys.platform.startswith("win"), reason="Unix loader-path warning")
+def test_connect_path_warns_when_loader_path_missing(monkeypatch, tmp_path):
+    iris.runtime.reset()
+    install_dir = tmp_path / "iris"
+    (install_dir / "bin").mkdir(parents=True)
+    (install_dir / "lib" / "python").mkdir(parents=True)
+    env_var = _iris_ep._bootstrap.get_loader_path_env_var()
+    monkeypatch.delenv(env_var, raising=False)
+
+    fake_module = types.SimpleNamespace(
+        __file__=str(install_dir / "bin" / "pythonint.so"),
+        cls=lambda name: {"class": name},
+        connect=lambda *args, **kwargs: {"ok": True},
+    )
+
+    def fake_import_module(name):
+        if name == "pythonint":
+            return fake_module
+        raise ModuleNotFoundError(name)
+
+    monkeypatch.setattr(_iris_ep._bootstrap.importlib, "import_module", fake_import_module)
+    monkeypatch.setattr(_iris_ep._bootstrap, "update_dynalib_path", lambda path: None)
+
+    with pytest.warns(RuntimeWarning, match=f"{env_var} does not include"):
+        iris.connect(path=install_dir)
+
+    iris.runtime.reset()
+
+
+@pytest.mark.skipif(sys.platform.startswith("win"), reason="Unix loader-path warning")
+def test_connect_path_warns_when_loader_path_points_elsewhere(monkeypatch, tmp_path):
+    iris.runtime.reset()
+    install_dir = tmp_path / "iris"
+    other_dir = tmp_path / "other"
+    (install_dir / "bin").mkdir(parents=True)
+    (install_dir / "lib" / "python").mkdir(parents=True)
+    other_dir.mkdir()
+    env_var = _iris_ep._bootstrap.get_loader_path_env_var()
+    monkeypatch.setenv(env_var, str(other_dir))
+
+    fake_module = types.SimpleNamespace(
+        __file__=str(install_dir / "bin" / "pythonint.so"),
+        cls=lambda name: {"class": name},
+        connect=lambda *args, **kwargs: {"ok": True},
+    )
+
+    def fake_import_module(name):
+        if name == "pythonint":
+            return fake_module
+        raise ModuleNotFoundError(name)
+
+    monkeypatch.setattr(_iris_ep._bootstrap.importlib, "import_module", fake_import_module)
+    monkeypatch.setattr(_iris_ep._bootstrap, "update_dynalib_path", lambda path: None)
+
+    with pytest.warns(RuntimeWarning, match=f"{env_var} does not include"):
+        iris.connect(path=install_dir)
+
+    iris.runtime.reset()
+
+
 def test_connect_path_rejects_pythonint_from_other_install(monkeypatch, tmp_path):
     iris.runtime.reset()
     install_dir = tmp_path / "iris"
     other_dir = tmp_path / "other-iris"
     (install_dir / "bin").mkdir(parents=True)
     (install_dir / "lib" / "python").mkdir(parents=True)
     (other_dir / "bin").mkdir(parents=True)
+    _set_loader_path(monkeypatch, install_dir)
 
     fake_module = types.SimpleNamespace(
         __file__=str(other_dir / "bin" / "pythonint.so"),
@@ -233,6 +303,7 @@ def test_connect_path_ignores_stale_pythonint_module(monkeypatch, tmp_path):
     (install_dir / "bin").mkdir(parents=True)
     (install_dir / "lib" / "python").mkdir(parents=True)
     (other_dir / "bin").mkdir(parents=True)
+    _set_loader_path(monkeypatch, install_dir)
 
     stale_module = types.SimpleNamespace(
         __file__=str(other_dir / "bin" / "pythonint.so"),
@@ -272,6 +343,7 @@ def test_connect_path_only_prioritizes_install_dir_during_pythonint_import(monke
     (install_dir / "bin").mkdir(parents=True)
     (install_dir / "lib" / "python").mkdir(parents=True)
     seen_import_path = []
+    _set_loader_path(monkeypatch, install_dir)
 
     fake_module = types.SimpleNamespace(
         __file__=str(install_dir / "bin" / "pythonint.so"),
@@ -308,6 +380,7 @@ def test_connect_path_warns_when_backend_has_no_connect(monkeypatch, tmp_path):
     install_dir = tmp_path / "iris"
     (install_dir / "bin").mkdir(parents=True)
     (install_dir / "lib" / "python").mkdir(parents=True)
+    _set_loader_path(monkeypatch, install_dir)
 
     fake_module = types.SimpleNamespace(
         __file__=str(install_dir / "bin" / "pythonint.so"),