Skip to content

armgit / dspy

Public Imported from GitHub
0

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.py
index 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 functools
import importlib
+import importlib.machinery
import importlib.metadata
import importlib.util
import inspect
import sys
+import threading
import types
from 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.cache
def 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 = None
np = 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 attribute
access 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 = None
extra: 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 = None
del parent
return _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 mod
diff --git a/tests/clients/test_lazy_litellm_import.py b/tests/clients/test_lazy_litellm_import.py
index 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.util
import sys
+import threading
+from concurrent.futures import ThreadPoolExecutor
import pytest
@@ -56,3 +58,29 @@ def test_embedder_litellm_use_raises_helpful_error_without_litellm(monkeypatch):
msg = str(exc_info.value)
assert "[litellm]" in msg
assert "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_litellm
diff --git a/tests/utils/test_lazy_import.py b/tests/utils/test_lazy_import.py
index 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 pytest
from 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)