Fix lazy utils imports for #21

Author: zh1peng

ChangLog.md

@@ -1,5 +1,17 @@
 # psyflow change log
 
+## 0.1.22 (2026-04-05)
+
+### Summary
+- Made `psyflow.utils` lazy-load PsychoPy-dependent helpers so importing `psyflow.utils` no longer eagerly imports `display` or `experiment`.
+- Removed the duplicate sim-side deadline helper and reused `psyflow.utils.trials.resolve_deadline()` from `psyflow.sim.context_helpers`.
+- Added smoke coverage for the import boundary and sim deadline resolution.
+- Addresses issue #21: `utils/__init__.py eager psychopy imports block cross-module reuse`.
+
+### Validation
+- `python -m unittest discover -s tests -p "test_smoke.py" -v` passed.
+- `python -m unittest discover -s tests -p "test_sim_golden.py" -v` passed.
+
 ## 0.1.21 (2026-03-04)
 
 ### Summary

psyflow/sim/context_helpers.py

@@ -3,15 +3,7 @@
 from typing import Any
 
 
-def _resolve_deadline(value: Any) -> float | None:
-    if isinstance(value, (int, float)):
-        return float(value)
-    if isinstance(value, (list, tuple)) and value:
-        try:
-            return float(max(value))
-        except (ValueError, TypeError):
-            return None
-    return None
+from ..utils.trials import resolve_deadline
 
 
 def set_trial_context(
@@ -35,7 +27,7 @@ def set_trial_context(
     return unit.set_state(
         trial_id=trial_id,
         phase=phase,
-        deadline_s=_resolve_deadline(deadline_s),
+        deadline_s=resolve_deadline(deadline_s),
         valid_keys=list(valid_keys or []),
         block_id=block_id,
         condition_id=condition_id,

psyflow/utils/__init__.py

@@ -1,22 +1,28 @@
 """Utility package for psyflow.
 
-Public usage:
-
-    from psyflow.utils import ...
+Keep this module lightweight: importing ``psyflow.utils`` should not eagerly
+import PsychoPy or other optional dependencies. Public symbols are exposed via
+lazy attribute access.
 """
 
-from .config import load_config, validate_config
-from .display import count_down
-from .experiment import initialize_exp
-from .ports import show_ports
-from .templates import taps
-from .trials import (
-    next_trial_id,
-    reset_trial_counter,
-    resolve_deadline,
-    resolve_trial_id,
-)
-from .voices import list_supported_voices
+from __future__ import annotations
+
+import importlib
+from typing import TYPE_CHECKING, Any
+
+_LAZY_ATTRS: dict[str, tuple[str, str]] = {
+    "count_down": ("psyflow.utils.display", "count_down"),
+    "initialize_exp": ("psyflow.utils.experiment", "initialize_exp"),
+    "list_supported_voices": ("psyflow.utils.voices", "list_supported_voices"),
+    "load_config": ("psyflow.utils.config", "load_config"),
+    "next_trial_id": ("psyflow.utils.trials", "next_trial_id"),
+    "reset_trial_counter": ("psyflow.utils.trials", "reset_trial_counter"),
+    "resolve_deadline": ("psyflow.utils.trials", "resolve_deadline"),
+    "resolve_trial_id": ("psyflow.utils.trials", "resolve_trial_id"),
+    "show_ports": ("psyflow.utils.ports", "show_ports"),
+    "taps": ("psyflow.utils.templates", "taps"),
+    "validate_config": ("psyflow.utils.config", "validate_config"),
+}
 
 __all__ = [
     "count_down",
@@ -31,3 +37,35 @@
     "taps",
     "validate_config",
 ]
+
+
+if TYPE_CHECKING:
+    from .config import load_config as load_config
+    from .config import validate_config as validate_config
+    from .display import count_down as count_down
+    from .experiment import initialize_exp as initialize_exp
+    from .ports import show_ports as show_ports
+    from .templates import taps as taps
+    from .trials import (
+        next_trial_id as next_trial_id,
+        reset_trial_counter as reset_trial_counter,
+        resolve_deadline as resolve_deadline,
+        resolve_trial_id as resolve_trial_id,
+    )
+    from .voices import list_supported_voices as list_supported_voices
+
+
+def __getattr__(name: str) -> Any:
+    spec = _LAZY_ATTRS.get(name)
+    if spec is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+    module_name, attr_name = spec
+    module = importlib.import_module(module_name)
+    value = getattr(module, attr_name)
+    globals()[name] = value  # cache for subsequent access
+    return value
+
+
+def __dir__() -> list[str]:
+    return sorted(set(globals().keys()) | set(_LAZY_ATTRS.keys()))

scripts/build-site-data.py

@@ -132,22 +132,47 @@ def source_url(module_name: str) -> str:
 
 
 def resolve_symbol_source(module_name: str, symbol: str) -> str:
-    try:
-        import_map = parse_import_map(module_name)
-    except FileNotFoundError:
-        return module_name
-    return import_map.get(symbol, module_name)
+    current_module = module_name
+    current_symbol = symbol
+    seen: set[tuple[str, str]] = set()
+
+    while (current_module, current_symbol) not in seen:
+        seen.add((current_module, current_symbol))
+
+        source_module = None
+        try:
+            import_map = parse_import_map(current_module)
+        except FileNotFoundError:
+            import_map = {}
+        source_module = import_map.get(current_symbol)
+
+        if source_module is None:
+            try:
+                lazy_map = {
+                    item.name: item.source_module
+                    for item in parse_lazy_attrs(current_module)
+                }
+            except FileNotFoundError:
+                lazy_map = {}
+            source_module = lazy_map.get(current_symbol)
+
+        if source_module is None or source_module == current_module:
+            return current_module
+
+        current_module = source_module
 
+    return current_module
 
-def parse_root_lazy_attrs() -> list[ExportSpec]:
-    text = read_text(ROOT / "psyflow" / "__init__.py")
+
+def parse_lazy_attrs(module_name: str) -> list[ExportSpec]:
+    text = read_text(module_file(module_name))
     pattern = re.compile(r'"([^"]+)":\s*\("([^"]+)",\s*"([^"]+)"\)')
     items: list[ExportSpec] = []
     for name, source_module, _attr_name in pattern.findall(text):
         items.append(
             ExportSpec(
                 name=name,
-                module="psyflow",
+                module=module_name,
                 source_module=source_module,
             )
         )
@@ -157,7 +182,7 @@ def parse_root_lazy_attrs() -> list[ExportSpec]:
 def build_inventory() -> list[dict[str, Any]]:
     groups: list[dict[str, Any]] = []
 
-    root_exports = parse_root_lazy_attrs()
+    root_exports = parse_lazy_attrs("psyflow")
     groups.append(
         {
             "module": "psyflow",
@@ -175,19 +200,31 @@ def build_inventory() -> list[dict[str, Any]]:
     )
 
     for module_name in ["psyflow.utils", "psyflow.io", "psyflow.qa", "psyflow.sim"]:
-        export_names = parse_dunder_all(module_name)
-        import_map = parse_import_map(module_name)
-        exports = []
-        for name in export_names:
-            source_module = import_map.get(name, module_name)
-            exports.append(
+        lazy_exports = parse_lazy_attrs(module_name)
+        if lazy_exports:
+            exports = [
                 {
-                    "name": name,
-                    "source_module": source_module,
-                    "summary": doc_summary(source_module, name),
-                    "source_url": source_url(source_module),
+                    "name": item.name,
+                    "source_module": item.source_module,
+                    "summary": doc_summary(item.source_module, item.name),
+                    "source_url": source_url(item.source_module),
                 }
-            )
+                for item in lazy_exports
+            ]
+        else:
+            export_names = parse_dunder_all(module_name)
+            import_map = parse_import_map(module_name)
+            exports = []
+            for name in export_names:
+                source_module = import_map.get(name, module_name)
+                exports.append(
+                    {
+                        "name": name,
+                        "source_module": source_module,
+                        "summary": doc_summary(source_module, name),
+                        "source_url": source_url(source_module),
+                    }
+                )
         groups.append(
             {
                 "module": module_name,

tests/test_smoke.py

@@ -3,15 +3,60 @@
 
 
 class TestImport(unittest.TestCase):
+    def _clear_psyflow_and_psychopy_modules(self) -> None:
+        for name in [
+            module_name
+            for module_name in list(sys.modules)
+            if module_name == "psyflow"
+            or module_name.startswith("psyflow.")
+            or module_name == "psychopy"
+            or module_name.startswith("psychopy.")
+        ]:
+            sys.modules.pop(name, None)
+
     def test_import_psyflow_does_not_import_psychopy(self):
         # The package should be importable without pulling in PsychoPy by default.
-        sys.modules.pop("psyflow", None)
-        sys.modules.pop("psychopy", None)
+        self._clear_psyflow_and_psychopy_modules()
 
         import psyflow  # noqa: F401
 
         self.assertNotIn("psychopy", sys.modules)
 
+    def test_import_psyflow_utils_does_not_import_psychopy(self):
+        self._clear_psyflow_and_psychopy_modules()
+
+        from psyflow.utils import resolve_deadline
+
+        self.assertEqual(resolve_deadline([0.25, 0.5]), 0.5)
+        self.assertNotIn("psychopy", sys.modules)
+        self.assertNotIn("psyflow.utils.display", sys.modules)
+        self.assertNotIn("psyflow.utils.experiment", sys.modules)
+
+
+class TestSimContextHelpers(unittest.TestCase):
+    def test_set_trial_context_resolves_deadline_sequences(self):
+        from psyflow.sim.context_helpers import set_trial_context
+
+        class DummyUnit:
+            def __init__(self) -> None:
+                self.state: dict[str, object] | None = None
+
+            def set_state(self, **kwargs):
+                self.state = kwargs
+                return kwargs
+
+        unit = DummyUnit()
+        result = set_trial_context(
+            unit,
+            trial_id=1,
+            phase="target",
+            deadline_s=[0.2, 0.5],
+            valid_keys=["space"],
+        )
+
+        self.assertEqual(result["deadline_s"], 0.5)
+        self.assertEqual(unit.state["deadline_s"], 0.5)
+
 
 class TestTaskSettings(unittest.TestCase):
     def test_from_dict_sets_derived_fields(self):

website/src/data/generated/changelog.json

@@ -1,4 +1,14 @@
 [
+  {
+    "version": "0.1.22",
+    "date": "2026-04-05",
+    "summary": [
+      "Made `psyflow.utils` lazy-load PsychoPy-dependent helpers so importing `psyflow.utils` no longer eagerly imports `display` or `experiment`.",
+      "Removed the duplicate sim-side deadline helper and reused `psyflow.utils.trials.resolve_deadline()` from `psyflow.sim.context_helpers`.",
+      "Added smoke coverage for the import boundary and sim deadline resolution.",
+      "Addresses issue #21: `utils/__init__.py eager psychopy imports block cross-module reuse`."
+    ]
+  },
   {
     "version": "0.1.21",
     "date": "2026-03-04",

website/src/data/generated/site-data.json

@@ -13,14 +13,15 @@
     }
   },
   "latest_release": {
-    "version": "0.1.21",
-    "date": "2026-03-04",
+    "version": "0.1.22",
+    "date": "2026-04-05",
     "summary": [
-      "Removed in-repo `skills/task-build` from `psyflow`.",
-      "Extracted `task-build` as a standalone canonical repository at `e:/Taskbeacon/skills/task-build`.",
-      "No backward-compatibility shim is kept in `psyflow`; skill ownership now lives outside the framework repo."
+      "Made `psyflow.utils` lazy-load PsychoPy-dependent helpers so importing `psyflow.utils` no longer eagerly imports `display` or `experiment`.",
+      "Removed the duplicate sim-side deadline helper and reused `psyflow.utils.trials.resolve_deadline()` from `psyflow.sim.context_helpers`.",
+      "Added smoke coverage for the import boundary and sim deadline resolution.",
+      "Addresses issue #21: `utils/__init__.py eager psychopy imports block cross-module reuse`."
     ]
   },
-  "release_count": 19,
+  "release_count": 20,
   "module_count": 5
 }