harden task config checks and audio stim typing

Author: zh1peng

ChangLog.md

@@ -1,5 +1,22 @@
 # psyflow change log
 
+## 0.1.5 (2026-02-12)
+
+### Summary
+- `StimUnit.add_stim(...)` now recognizes PsychoPy runtime audio backends (via `_SoundBase` and resolved backend classes), fixing false rejections of valid sound stimuli.
+- Unsupported stimulus objects in `StimUnit.add_stim(...)` now emit a warning and raise a clearer `TypeError` that lists supported classes.
+- `TaskSettings.from_dict(...)` was hardened:
+  - validates that input config is a dict,
+  - passes only `init=True` dataclass fields into constructor,
+  - validates `trial_per_block` / `trials_per_block` aliases for consistency,
+  - enforces declared trials-per-block matches `ceil(total_trials / total_blocks)` when provided.
+- `initialize_exp(...)` now defaults to `settings.screen` when `screen_id` is not explicitly passed.
+
+### Files
+- `psyflow/StimUnit.py`
+- `psyflow/TaskSettings.py`
+- `psyflow/utils/experiment.py`
+
 ## 0.1.4 (2026-02-12)
 
 ### Summary

psyflow/StimUnit.py

@@ -1,9 +1,36 @@
 from psychopy import core, visual, logging, sound
 from psychopy.hardware.keyboard import Keyboard
-from typing import Callable, Optional, List, Dict, Any, Union
+from typing import Callable, Optional, List, Dict, Any, Sequence, TypeAlias, Union
+import importlib
 import random
 from .qa.context import get_context
 from .io.events import TriggerEvent
+from psychopy.sound._base import _SoundBase
+
+
+def _resolve_audio_stim_types() -> tuple[type, ...]:
+    """Resolve concrete PsychoPy sound classes used at runtime."""
+    types: list[type] = [_SoundBase]
+    candidates = (
+        ("psychopy.sound.backend_ptb", "SoundPTB"),
+        ("psychopy.sound.backend_sounddevice", "SoundDeviceSound"),
+        ("psychopy.sound.backend_pyo", "SoundPyo"),
+        ("psychopy.sound.backend_pygame", "SoundPygame"),
+    )
+    for module_name, class_name in candidates:
+        try:
+            module = importlib.import_module(module_name)
+            cls = getattr(module, class_name, None)
+            if isinstance(cls, type) and cls not in types:
+                types.append(cls)
+        except Exception:
+            continue
+    return tuple(types)
+
+
+AUDIO_STIM_TYPES = _resolve_audio_stim_types()
+SUPPORTED_STIM_TYPES = (visual.BaseVisualStim,) + AUDIO_STIM_TYPES
+SupportedStim: TypeAlias = Union[visual.BaseVisualStim, _SoundBase]
 
 class StimUnit:
     """
@@ -78,7 +105,7 @@ def _qa_scale_duration(self, nominal_s: float) -> tuple[float, int, bool]:
         used = max(self.frame_time, n_frames * self.frame_time)
         return used, n_frames, True
 
-    def add_stim(self, *stims: Union[visual.BaseVisualStim, sound.Sound, List[Union[visual.BaseVisualStim, sound.Sound]]]) -> "StimUnit":
+    def add_stim(self, *stims: Union[SupportedStim, Sequence[SupportedStim]]) -> "StimUnit":
         """
         Add one or more visual or sound stimuli to the trial.
 
@@ -101,8 +128,14 @@ def add_stim(self, *stims: Union[visual.BaseVisualStim, sound.Sound, List[Union[
             stims = stims[0]
 
         for stim in stims:
-            if not isinstance(stim, (visual.BaseVisualStim, sound.Sound)):
-                raise TypeError(f"add_stim expects visual or sound stimuli, got {type(stim)}")
+            if not isinstance(stim, SUPPORTED_STIM_TYPES):
+                supported = ", ".join(sorted({t.__name__ for t in SUPPORTED_STIM_TYPES}))
+                msg = (
+                    "add_stim got unsupported object type "
+                    f"{type(stim).__name__}. Supported types include: {supported}"
+                )
+                logging.warning(f"[StimUnit] {msg}")
+                raise TypeError(msg)
             self.stimuli.append(stim)
 
         return self

psyflow/TaskSettings.py

@@ -178,11 +178,57 @@ def from_dict(cls, config: dict):
         >>> cfg = {'total_blocks': 2, 'total_trials': 20}
         >>> TaskSettings.from_dict(cfg)
         """
-        known_keys = set(f.name for f in cls.__dataclass_fields__.values())
+        if not isinstance(config, dict):
+            raise TypeError(f"config must be a dict, got {type(config)}")
+
+        # Only fields with init=True can be passed to the dataclass constructor.
+        known_keys = {
+            name for name, field_def in cls.__dataclass_fields__.items()
+            if field_def.init
+        }
         init_args = {k: v for k, v in config.items() if k in known_keys}
         extras = {k: v for k, v in config.items() if k not in known_keys}
 
         settings = cls(**init_args)
+
+        # Optional config alias guardrail:
+        # if trial_per_block is provided in task config, it must match the derived value.
+        tpb_declared = None
+        if "trial_per_block" in extras:
+            tpb_declared = extras.pop("trial_per_block")
+        if "trials_per_block" in extras:
+            tpb_alt = extras.pop("trials_per_block")
+            if tpb_declared is None:
+                tpb_declared = tpb_alt
+            elif int(tpb_declared) != int(tpb_alt):
+                raise ValueError(
+                    "Inconsistent task config: both 'trial_per_block' and "
+                    f"'trials_per_block' were provided but differ "
+                    f"({tpb_declared} vs {tpb_alt})."
+                )
+
+        if tpb_declared is not None:
+            try:
+                tpb_declared_i = int(tpb_declared)
+            except Exception as exc:
+                raise TypeError(
+                    "task.trial_per_block must be an int when provided, got "
+                    f"{tpb_declared!r}"
+                ) from exc
+
+            if tpb_declared_i != settings.trials_per_block:
+                raise ValueError(
+                    "Inconsistent task config: "
+                    f"trial_per_block={tpb_declared_i} but "
+                    "ceil(total_trials/total_blocks)="
+                    f"{settings.trials_per_block} "
+                    f"(total_trials={settings.total_trials}, "
+                    f"total_blocks={settings.total_blocks})."
+                )
+            # Keep both names available for task code that reads either alias.
+            settings.trial_per_block = tpb_declared_i
+            settings.trials_per_block = tpb_declared_i
+
         for k, v in extras.items():
             setattr(settings, k, v)
         return settings

psyflow/utils/experiment.py

@@ -1,23 +1,25 @@
 """Experiment/window bootstrap utilities."""
 
-from typing import Tuple
+from typing import Optional, Tuple
 
 from psychopy import core, event, logging, monitors
 from psychopy.hardware import keyboard
 from psychopy.visual import Window
 
 
-def initialize_exp(settings, screen_id: int = 1) -> Tuple[Window, keyboard.Keyboard]:
+def initialize_exp(settings, screen_id: Optional[int] = None) -> Tuple[Window, keyboard.Keyboard]:
     """Set up the PsychoPy window, keyboard and logging."""
     mon = monitors.Monitor("tempMonitor")
     mon.setWidth(getattr(settings, "monitor_width_cm", 35.5))
     mon.setDistance(getattr(settings, "monitor_distance_cm", 60))
     mon.setSizePix(getattr(settings, "size", [1024, 768]))
 
+    resolved_screen = getattr(settings, "screen", 0) if screen_id is None else screen_id
+
     win = Window(
         size=getattr(settings, "size", [1024, 768]),
         fullscr=getattr(settings, "fullscreen", False),
-        screen=screen_id,
+        screen=resolved_screen,
         monitor=mon,
         units=getattr(settings, "units", "pix"),
         color=getattr(settings, "bg_color", [0, 0, 0]),
@@ -53,4 +55,3 @@ def initialize_exp(settings, screen_id: int = 1) -> Tuple[Window, keyboard.Keybo
     logging.console.setLevel(logging.INFO)
 
     return win, kb
-