DSPy: The framework for programming—not prompting—language models
Python
Make lazy optional imports thread-safe (#9840)
Maxime Rivest46c88455f8cc
diff --git a/dspy/utils/lazy_import.py b/dspy/utils/lazy_import.pyindex 1cebf13a9..2a9314727 100644--- a/dspy/utils/lazy_import.py+++ b/dspy/utils/lazy_import.py@@ -12,16 +12,18 @@ real import until first attribute access:If the package is not installed, the first attribute access raises`ImportError` with an install hint.-The lazy-load machinery is vendored from *lazy_loader* (BSD-3, Scientific-Python team) and uses `importlib.util.LazyLoader` under the hood.+Lazy modules are materialized under a per-module lock so concurrent first use+cannot expose a partially initialized module."""import functoolsimport importlib+import importlib.machineryimport importlib.metadataimport importlib.utilimport inspectimport sys+import threadingimport typesfrom typing import Any@@ -46,6 +48,15 @@ _INSTALL_HINTS: dict[str, str] = {}+_lazy_module_locks: dict[str, threading.RLock] = {}+_lazy_module_locks_lock = threading.Lock()+++def _get_lazy_module_lock(module: str) -> threading.RLock:+ with _lazy_module_locks_lock:+ return _lazy_module_locks.setdefault(module, threading.RLock())++class _MissingModule(types.ModuleType):"""Stand-in returned by `require()` when a package is not installed.@@ -68,6 +79,55 @@ class _MissingModule(types.ModuleType):)+class _LazyModule(types.ModuleType):+ """Module proxy that imports the real module on first attribute access.++ Attribute assignment also materializes the real module so configuration writes apply to the real dependency.+ """++ def __init__(self, module: str, spec: importlib.machinery.ModuleSpec, lock: threading.RLock):+ super().__init__(module)+ self.__spec__ = spec+ self.__loader__ = spec.loader+ self.__package__ = spec.parent+ if spec.submodule_search_locations is not None:+ self.__path__ = spec.submodule_search_locations+ self._dspy_lazy_spec = spec+ self._dspy_lazy_lock = lock++ def _load(self) -> types.ModuleType:+ # The proxy starts in sys.modules, then the first attribute access swaps in and executes the real module under+ # the per-module lock. If import fails, restore the proxy so later accesses can retry and still share the lock.+ # Return sys.modules after execution because a module may replace itself while importing.+ module_name = self.__name__+ with self._dspy_lazy_lock:+ loaded = sys.modules.get(module_name)+ if loaded is not None and loaded is not self:+ return loaded++ spec = self._dspy_lazy_spec+ module = importlib.util.module_from_spec(spec)+ sys.modules[module_name] = module+ try:+ spec.loader.exec_module(module)+ except Exception:+ sys.modules[module_name] = self+ raise+ return sys.modules.get(module_name, module)++ def __getattr__(self, attr: str) -> Any:+ return getattr(self._load(), attr)++ def __setattr__(self, attr: str, value: Any) -> None:+ if attr.startswith("_dspy_lazy_") or attr in {"__spec__", "__loader__", "__package__", "__path__"}:+ super().__setattr__(attr, value)+ else:+ setattr(self._load(), attr, value)++ def __dir__(self) -> list[str]:+ return dir(self._load())++@functools.cachedef is_available(module: str) -> bool:"""Return True if *module* can be imported, without actually importing it."""@@ -84,8 +144,8 @@ def require(module: str, *, extra: str | None = None, feature: str | None = Nonenp = require("numpy")- **Installed** -- returns a `LazyLoader`-wrapped module. The real import- happens on first attribute access; afterwards the object is a plain module.+ **Installed** -- returns a `_LazyModule` proxy. The real import happens on first attribute access, guarded by a+ per-module lock so concurrent first use cannot observe a partially initialized module.**Not installed** -- returns a `_MissingModule` stub. The first attributeaccess raises `ImportError` with a `pip install dspy[…]` hint and the@@ -96,10 +156,12 @@ def require(module: str, *, extra: str | None = None, feature: str | None = Noneextra: Name of the dspy extra that provides this dep.feature: Label shown in the error (e.g. `"dspy.Embeddings"`)."""- if module in sys.modules:- return sys.modules[module]+ lock = _get_lazy_module_lock(module)+ with lock:+ if module in sys.modules:+ return sys.modules[module]- spec = importlib.util.find_spec(module)+ spec = importlib.util.find_spec(module)if spec is None or spec.loader is None:top = module.split(".", 1)[0]feat = feature or "this feature"@@ -119,9 +181,10 @@ def require(module: str, *, extra: str | None = None, feature: str | None = Nonedel parentreturn _MissingModule(module, message, frame_data)- loader = importlib.util.LazyLoader(spec.loader)- spec.loader = loader- mod = importlib.util.module_from_spec(spec)- sys.modules[module] = mod- loader.exec_module(mod)- return mod+ with lock:+ if module in sys.modules:+ return sys.modules[module]++ mod = _LazyModule(module, spec, lock)+ sys.modules[module] = mod+ return moddiff --git a/tests/clients/test_lazy_litellm_import.py b/tests/clients/test_lazy_litellm_import.pyindex 5eeec4092..8d3b7b59e 100644--- a/tests/clients/test_lazy_litellm_import.py+++ b/tests/clients/test_lazy_litellm_import.py@@ -1,5 +1,7 @@import importlib.utilimport sys+import threading+from concurrent.futures import ThreadPoolExecutorimport pytest@@ -56,3 +58,29 @@ def test_embedder_litellm_use_raises_helpful_error_without_litellm(monkeypatch):msg = str(exc_info.value)assert "[litellm]" in msgassert "dspy.Embedder" in msg+++def test_concurrent_lm_first_use_materializes_litellm_once():+ import dspy+ from dspy.clients._litellm import get_litellm++ original_litellm = sys.modules.pop("litellm", None)+ get_litellm.cache_clear()+ try:+ threads = 8+ barrier = threading.Barrier(threads)++ def supports_function_calling(_):+ barrier.wait()+ lm = dspy.LM("openai/gpt-4o-mini", cache=False, num_retries=0)+ return lm.supports_function_calling++ with ThreadPoolExecutor(max_workers=threads) as executor:+ results = list(executor.map(supports_function_calling, range(threads)))++ assert len(results) == threads+ assert all(isinstance(result, bool) for result in results)+ finally:+ get_litellm.cache_clear()+ if original_litellm is not None:+ sys.modules["litellm"] = original_litellmdiff --git a/tests/utils/test_lazy_import.py b/tests/utils/test_lazy_import.pyindex 85495641b..b65e6d83c 100644--- a/tests/utils/test_lazy_import.py+++ b/tests/utils/test_lazy_import.py@@ -1,3 +1,7 @@+import sys+import threading+from concurrent.futures import ThreadPoolExecutor+import pytestfrom dspy.utils.lazy_import import _INSTALL_HINTS, _detect_dspy_dist, _MissingModule, is_available, require@@ -31,12 +35,49 @@ def test_require_returns_lazy_module_when_present():def test_require_returns_cached_module():- import sys-mod = require("json")assert mod is sys.modules["json"]+def test_require_is_safe_under_concurrent_first_use(tmp_path, monkeypatch):+ module_name = "dspy_lazy_threaded_module"+ counter_path = tmp_path / "imports.txt"+ monkeypatch.syspath_prepend(tmp_path)+ monkeypatch.delitem(sys.modules, module_name, raising=False)+ (tmp_path / f"{module_name}.py").write_text(+ "import pathlib\n"+ "import time\n"+ "time.sleep(0.1)\n"+ f"path = pathlib.Path({str(counter_path)!r})\n"+ "path.write_text(path.read_text() + '1' if path.exists() else '1')\n"+ "value = 42\n"+ )++ threads = 8+ barrier = threading.Barrier(threads)++ def read_value(_):+ barrier.wait()+ return require(module_name).value++ with ThreadPoolExecutor(max_workers=threads) as executor:+ assert list(executor.map(read_value, range(threads))) == [42] * threads++ assert counter_path.read_text() == "1"+++def test_require_assignment_updates_materialized_module(tmp_path, monkeypatch):+ module_name = "dspy_lazy_assignment_module"+ monkeypatch.syspath_prepend(tmp_path)+ monkeypatch.delitem(sys.modules, module_name, raising=False)+ (tmp_path / f"{module_name}.py").write_text("value = 1\n")++ mod = require(module_name)+ mod.value = 2++ assert sys.modules[module_name].value == 2++def test_require_returns_stub_when_missing():stub = require("definitely_not_a_real_module_xyz", feature="dspy.X")assert isinstance(stub, _MissingModule)