psychopy 2025.1.0__py3-none-any.whl → 2025.2.1__py3-none-any.whl

psychopy/experiment/params.py

@@ -16,12 +16,13 @@ The code that writes out a *_lastrun.py experiment file is (in order):
     settings.SettingsComponent.writeEndCode()
 """
 import functools
+import json
 from xml.etree.ElementTree import Element
 
 import re
 from pathlib import Path
 
-from psychopy import logging
+from psychopy import data, logging
 from . import utils
 from . import py2js
 
@@ -55,6 +56,8 @@ inputDefaults = {
 # these are parameters which once existed but are no longer needed, so inclusion in this list will 
 # silence any "future version" warnings
 legacyParams = [
+    # settings params from the early days of PsychoJS
+    "JS libs", "OSF Project ID"
     # in 2021.1, we standardised colorSpace to be object-wide rather than param-specific
     "lineColorSpace", "borderColorSpace", "fillColorSpace", "foreColorSpace", 
     # in 2024.2.0, we removed some superfluous params from the pupil labs backend
@@ -230,7 +233,7 @@ class Param():
                 return "%i" % self.val  # int and float -> str(int)
             except TypeError:
                 return "%s" % self.val  # try array of float instead?
-        elif self.valType in ['extendedStr','str', 'file', 'table']:
+        elif self.valType in ['extendedStr', 'str', 'file', 'table', 'device']:
             # at least 1 non-escaped '$' anywhere --> code wanted
             # return str if code wanted
             # return repr if str wanted; this neatly handles "it's" and 'He
@@ -300,13 +303,19 @@ class Param():
                 # Otherwise, treat as string
                 return repr(val)
         elif self.valType == 'list':
-            valid, val = self.dollarSyntax()
-            val = toList(val)
-            return "{}".format(val)
+            if self.inputType == "fileList":
+                # treat each item as a string-type param
+                output = []
+                for item in data.utils.listFromString(self.val):
+                    item = str(Param(item, "file"))
+                    output.append(item)
+                return "[{}]".format(",".join(output))
+            else:
+                valid, val = self.dollarSyntax()
+                val = toList(val)
+                return "{}".format(val)
         elif self.valType == 'fixedList':
             return "{}".format(self.val)
-        elif self.valType == 'fileList':
-            return "{}".format(self.val)
         elif self.valType == 'bool':
             if utils.scriptTarget == "PsychoJS":
                 return ("%s" % self.val).lower()  # make True -> "true"
@@ -372,12 +381,41 @@ class Param():
             allowedLabels=self.allowedLabels,
             direct=self.direct,
             canBePath=self.canBePath,
-            categ=self.categ
+            categ=self.categ,
+            ctrlParams=self.ctrlParams
         )
 
     def __deepcopy__(self, memo):
         return self.copy()
-
+    
+    @classmethod
+    def fromJSON(cls, data):
+        # initialise
+        param = Param(
+            "",
+            "code",
+        )
+        # apply
+        param.applyJSON(data)
+    
+    def applyJSON(self, data):
+        if "val" in data:
+            self.val = data['val']
+        if "valType" in data:
+            self.valType = data['valType']
+        if "updates" in data:
+            self.updates = "{}".format(data['updates'])
+        if "plugin" in data:
+            self.plugin = "{}".format(data['plugin'])
+    
+    def toJSON(self):
+        return {
+            'val': self.val,
+            'valType': self.valType,
+            'updates': "{}".format(self.updates),
+            'plugin': "{}".format(self.plugin)
+        }
+    
     @property
     def _xml(self):
         # Make root element
@@ -425,7 +463,7 @@ class Param():
                     return True, val
             else:
                 # If value does not begin with an unescaped $, treat it as a string
-                if not re.findall(r"(?<!\\)\$", val):
+                if not re.findall(r"(?<!\\)\$", str(val)):
                     # Return if all $ are escaped (\$)
                     return True, val
         else:

psychopy/experiment/plugins.py

@@ -3,120 +3,40 @@ from psychopy import logging
 
 class PluginDevicesMixin:
     """
-    Mixin for Components and Routines which adds behaviour to get parameters and values from
-    plugins and use them to create different devices for different plugin backends.
+    Legacy placeholder class - used to handle device backends added by plugins before Builder had a dedicated device manager.
     """
-
-    def __init_subclass__(cls):
-        # list of backends for this component - each should be a subclass of DeviceBackend
-        cls.backends = []
-
-    def loadBackends(self):
-        # add params from backends
-        for backend in self.backends:
-            # get params using backend's method
-            params, order = backend.getParams(self)
-            # get reference to package
-            plugin = None
-            if hasattr(backend, "__module__") and backend.__module__:
-                pkg = backend.__module__.split(".")[0]
-                if pkg != "psychopy":
-                    plugin = pkg
-            # add order
-            self.order.extend(order)
-            # add any params
-            for key, param in params.items():
-                if key in self.params:
-                    # if this param already exists (i.e. from saved data), get the saved val
-                    param.val = self.params[key].val
-                    param.updates = self.params[key].updates
-                # add param
-                self.params[key] = param
-                # store plugin reference
-                self.params[key].plugin = plugin
-
-            # add dependencies so that backend params are only shown for this backend
-            for name in params:
-                self.depends.append(
-                    {
-                        "dependsOn": "deviceBackend",  # if...
-                        "condition": f"== '{backend.key}'",  # meets...
-                        "param": name,  # then...
-                        "true": "show",  # should...
-                        "false": "hide",  # otherwise...
-                    }
-                )
-            # add requirements
-            backend.addRequirements(self)
-
-    def getBackendKeys(self):
-        keys = []
-        for backend in self.backends:
-            keys.append(backend.key)
-
-        return keys
-
-    def getBackendLabels(self):
-        labels = []
-        for backend in self.backends:
-            labels.append(backend.label)
-
-        return labels
-
-    def writeDeviceCode(self, buff):
-        # write init code from backend
-        for backend in self.backends:
-            if backend.key == self.params['deviceBackend']:
-                backend.writeDeviceCode(self, buff)
+    pass
 
 
-class DeviceBackend:
-    # which component is this backend for?
+from .devices import DeviceBackend
+class DeviceBackend(DeviceBackend):
+    """
+    Legacy wrapper to convert plugins.DeviceBackend classes to the newer devices.DeviceBackend class.
+    """
+    key = "microphone"
+    label = ""
+    component = None
+    deviceClasses = ["psychopy.hardware.soundsensor.MicrophoneSoundSensor"]
     component = PluginDevicesMixin
-    # what value should Builder use for this backend?
     key = ""
-    # what label should be displayed by Builder for this backend?
     label = ""
-    # values to append to the component's deviceClasses array
     deviceClasses = []
 
-    def __init_subclass__(cls):
-        logging.debug(
-            f"Registered backend for {cls.component.__name__}: {cls.label} ({cls.key}) from "
-            f"{cls.__module__}:{cls.__name__}"
-        )
-        # add class to list of backends for ButtonBoxComponent
-        cls.component.backends = cls.component.backends.copy()
-        cls.component.backends.append(cls)
-        # add device classes to component
-        if cls is not PluginDevicesMixin and hasattr(cls.component, "deviceClasses"):
-            for deviceClass in cls.deviceClasses:
-                if deviceClass not in cls.component.deviceClasses:
-                    cls.component.deviceClasses = cls.component.deviceClasses.copy()
-                    cls.component.deviceClasses.append(deviceClass)
-
-    def getParams(self):
-        """
-        Get parameters from this backend to add to each new instance of ButtonBoxComponent
-
-        Returns
-        -------
-        dict[str:Param]
-            Dict of Param objects, which will be added to any Button Box Component's params, along
-            with a dependency to only show them when this backend is selected
-        list[str]
-            List of param names, defining the order in which params should appear
-        """
-        raise NotImplementedError()
 
-    def addRequirements(self):
-        """
-        Add any required module/package imports for this backend
-        """
-        return
-
-    def writeDeviceCode(self, buff):
-        """
-        Write the code to create a device for this backend
-        """
-        raise NotImplementedError()
+    def __init_subclass__(cls):
+        # if component was specified by class attribute, register it
+        if cls.component is not PluginDevicesMixin:
+            cls.component.registerBackend(cls)
+        # if we can get params without initialising, add them to the Component's legacy list
+        # (as they're now parameters of the device rather than the Component)
+        try:
+            for name in cls.getParams(None)[0]:
+                cls.component.legacyParams.append(name)
+        except AttributeError:
+            pass
+        # placeholder value for icon
+        cls.icon = None
+        # use label for backendLabel
+        cls.backendLabel = cls.label
+        # a backend only has 1 device now
+        cls.deviceClass = cls.deviceClasses[0]

psychopy/experiment/py2js_transpiler.py

@@ -12,7 +12,7 @@ import re
 try:
     from metapensiero.pj.api import translates
 except ImportError:
-    pass  # metapensiero not installed
+    translates = None # metapensiero not installed
 
 import astunparse
 

psychopy/experiment/routines/__init__.py

@@ -8,7 +8,7 @@
 # Distributed under the terms of the GNU General Public License (GPL).
 
 from importlib import import_module
-from ._base import BaseStandaloneRoutine, BaseValidatorRoutine, Routine
+from ._base import BaseStandaloneRoutine, BaseDeviceRoutine, BaseValidatorRoutine, Routine
 from .unknown import UnknownRoutine
 from pathlib import Path
 from psychopy import logging

psychopy/experiment/routines/_base.py

@@ -16,6 +16,7 @@ from pathlib import Path
 
 from psychopy.experiment.components.static import StaticComponent
 from psychopy.experiment.components.routineSettings import RoutineSettingsComponent
+from psychopy.experiment.devices import DeviceMixin
 from psychopy.localization import _translate
 from psychopy.experiment import Param
 
@@ -32,6 +33,9 @@ class BaseStandaloneRoutine:
     beta = False
     # hide this Component in Builder view?
     hidden = False
+    # are there any known legacy params for this Routine?
+    # these will be removed & warnings ignored on experiment load
+    legacyParams = []
 
     def __init__(self, exp, name='',
                  stopType='duration (s)', stopVal='',
@@ -47,7 +51,7 @@ class BaseStandaloneRoutine:
         msg = _translate(
             "Name of this Routine (alphanumeric or _, no spaces)")
         self.params['name'] = Param(name,
-                                    valType='code', inputType="single", categ='Basic',
+                                    valType='code', inputType="name", categ='Basic',
                                     hint=msg,
                                     label=_translate('Name'))
 
@@ -374,14 +378,41 @@ class BaseStandaloneRoutine:
         self.params['disabled'].val = value
 
 
-class BaseValidatorRoutine(BaseStandaloneRoutine):
+class BaseDeviceRoutine(BaseStandaloneRoutine, DeviceMixin):
+    """
+    Base class for most routines which interface with a hardware device.
+    """
+    def __init__(
+            self, exp,
+            # basic
+            name='',
+            stopType='duration (s)', stopVal='',
+            # device
+            deviceLabel="",
+            # testing
+            disabled=False
+    ):
+        # initialise base component
+        BaseStandaloneRoutine.__init__(
+            self, exp, 
+            # basic
+            name=name,
+            stopType=stopType, stopVal=stopVal,
+            # testing
+            disabled=disabled
+        )
+        # add device stuff
+        self.addDeviceParams(
+            defaultLabel=deviceLabel
+        )
+
+
+class BaseValidatorRoutine(BaseDeviceRoutine):
     """
     Subcategory of Standalone Routine, which sets up a "validator" - an object which is linked to in the Testing tab
     of another Component and validates that the component behaved as expected. Any validator Routines should subclass
     this rather than BaseStandaloneRoutine.
     """
-    # list of class strings (readable by DeviceManager) which this component's device could be
-    deviceClasses = []
 
     def writeRoutineStartValidationCode(self, buff, stim):
         """
@@ -667,19 +698,23 @@ class Routine(list):
         )
         buff.writeIndentedLines(code % self.params)
 
-        code = ("for thisComponent in {name}.components:\n"
-                "    thisComponent.tStart = None\n"
-                "    thisComponent.tStop = None\n"
-                "    thisComponent.tStartRefresh = None\n"
-                "    thisComponent.tStopRefresh = None\n"
-                "    if hasattr(thisComponent, 'status'):\n"
-                "        thisComponent.status = NOT_STARTED\n"
-                "# reset timers\n"
-                't = 0\n'
-                '_timeToFirstFrame = win.getFutureFlipTime(clock="now")\n'
-                # '{clockName}.reset(-_timeToFirstFrame)  # t0 is time of first possible flip\n'
-                'frameN = -1\n'
-                '\n# --- Run Routine "{name}" ---\n')
+        code = (
+            "for thisComponent in {name}.components:\n"
+            "    thisComponent.tStart = None\n"
+            "    thisComponent.tStop = None\n"
+            "    thisComponent.tStartRefresh = None\n"
+            "    thisComponent.tStopRefresh = None\n"
+            "    if hasattr(thisComponent, 'status'):\n"
+            "        thisComponent.status = NOT_STARTED\n"
+            "# reset timers\n"
+            't = 0\n'
+            '_timeToFirstFrame = win.getFutureFlipTime(clock="now")\n'
+            # '{clockName}.reset(-_timeToFirstFrame)  # t0 is time of first possible flip\n'
+            'frameN = -1\n'
+            '\n'
+            '# --- Run Routine "{name}" ---\n'
+            'thisExp.currentRoutine = {name}\n'
+        )
         buff.writeIndentedLines(code.format(name=self.name,
                                             clockName=self._clockName))
 
@@ -760,16 +795,16 @@ class Routine(list):
         # are we done yet?
         code = (
             '\n'
-            '# check if all components have finished\n'
-            'if not continueRoutine:  # a component has requested a '
-            'forced-end of Routine\n'
+            '# has a Component requested the Routine to end?\n'
+            'if not continueRoutine:\n'
             '    %(name)s.forceEnded = routineForceEnded = True\n'
+            '# has the Routine been forcibly ended?\n'
+            'if %(name)s.forceEnded or routineForceEnded:\n'
             '    break\n'
-            'continueRoutine = False  # will revert to True if at least '
-            'one component still running\n'
+            '# has every Component finished?\n'
+            'continueRoutine = False\n'
             'for thisComponent in %(name)s.components:\n'
-            '    if hasattr(thisComponent, "status") and '
-            'thisComponent.status != FINISHED:\n'
+            '    if hasattr(thisComponent, "status") and thisComponent.status != FINISHED:\n'
             '        continueRoutine = True\n'
             '        break  # at least one component has not yet finished\n')
         buff.writeIndentedLines(code % self.params)

psychopy/experiment/routines/audioValidator/__init__.py

@@ -2,15 +2,16 @@
 # -*- coding: utf-8 -*-
 
 from pathlib import Path
+from psychopy.preferences import prefs
 from psychopy.alerts._alerts import alert
 from psychopy.experiment import Param
-from psychopy.experiment.plugins import PluginDevicesMixin, DeviceBackend
+from psychopy.experiment.plugins import DeviceBackend
 from psychopy.experiment.components import getInitVals
-from psychopy.experiment.routines import Routine, BaseValidatorRoutine
+from psychopy.experiment.routines import Routine, BaseDeviceRoutine
 from psychopy.localization import _translate
 
 
-class AudioValidatorRoutine(BaseValidatorRoutine, PluginDevicesMixin):
+class AudioValidatorRoutine(BaseDeviceRoutine):
     """
     Use a sound sensor (voicekey or microphone) to confirm that audio stimuli are presented when they should be.
     """
@@ -22,16 +23,24 @@ class AudioValidatorRoutine(BaseValidatorRoutine, PluginDevicesMixin):
         "Use a sound sensor to confirm that audio stimuli are presented when they should "
         "be."
     )
-    deviceClasses = ["psychopy.validation.voicekey.AudioValidator"]
     version = "2025.1.0"
+    legacyParams = [
+        # old device setup params, no longer needed as this is handled by DeviceManager
+        "deviceBackend",
+        "meMicrophone",
+        "meThreshold",
+        "meRange",
+        "meSamplingWindow",
+    ]
 
     def __init__(
             self,
             # basic
             exp, name='audioVal',
-            threshold=0.5,
             # device
-            deviceLabel="", deviceBackend="microphone", channel="0",
+            deviceLabel="", channel="0",
+            # legacy
+            threshold=0.5, deviceBackend="microphone",
     ):
 
         self.exp = exp  # so we can access the experiment if necess
@@ -43,44 +52,13 @@ class AudioValidatorRoutine(BaseValidatorRoutine, PluginDevicesMixin):
 
         exp.requirePsychopyLibs(["validation"])
 
-        # --- Basic ---
-        self.order += [
-            "threshold",
-        ]
-        self.params['threshold'] = Param(
-            threshold, valType="code", inputType="single", categ="Basic",
-            label=_translate("Threshold"),
-            hint=_translate(
-                "Arbitrary volume threshold at which the sound sensor should register a positive, units go from 0 (least volume) to 1 (most volume)."
-            )
-        )
         del self.params['stopType']
         del self.params['stopVal']
 
         # --- Device ---
         self.order += [
-            "deviceLabel",
-            "deviceBackend",
             "channel",
         ]
-        self.params['deviceLabel'] = Param(
-            deviceLabel, valType="str", inputType="single", categ="Device",
-            label=_translate("Device name"),
-            hint=_translate(
-                "A name to refer to this Component's associated hardware device by. If using the "
-                "same device for multiple components, be sure to use the same name here."
-            )
-        )
-        self.params['deviceBackend'] = Param(
-            deviceBackend, valType="code", inputType="choice", categ="Device",
-            allowedVals=self.getBackendKeys,
-            allowedLabels=self.getBackendLabels,
-            label=_translate("Sound sensor type"),
-            hint=_translate(
-                "Type of sound sensor to use."
-            ),
-            direct=False
-        )
         self.params['channel'] = Param(
             channel, valType="code", inputType="single", categ="Device",
             label=_translate("Sound sensor channel"),
@@ -91,47 +69,14 @@ class AudioValidatorRoutine(BaseValidatorRoutine, PluginDevicesMixin):
             )
         )
 
-        self.loadBackends()
-
-    def writeDeviceCode(self, buff):
-        """
-        Code to setup the CameraDevice for this component.
-
-        Parameters
-        ----------
-        buff : io.StringIO
-            Text buffer to write code to.
-        """
-        # do usual backend-specific device code writing
-        PluginDevicesMixin.writeDeviceCode(self, buff)
-        # get inits
-        inits = getInitVals(self.params)
-        # get device handle
-        code = (
-            "%(deviceLabelCode)s = deviceManager.getDevice(%(deviceLabel)s)\n"
-            "%(deviceLabelCode)s.setThreshold(%(threshold)s, channel=%(channel)s)\n"
-        )
-        buff.writeOnceIndentedLines(code % inits)
-
     def writeMainCode(self, buff):
         inits = getInitVals(self.params)
-        # get diode
-        code = (
-            "# diode object for %(name)s\n"
-            "%(name)sDevice = deviceManager.getDevice(%(deviceLabel)s)\n"
-        )
-        buff.writeIndentedLines(code % inits)
-
-        if self.params['threshold']:
-            code = (
-                "%(name)sDevice.setThreshold(%(threshold)s, channel=%(channel)s)\n"
-            )
-            buff.writeIndentedLines(code % inits)
         # create validator object
         code = (
             "# validator object for %(name)s\n"
             "%(name)s = validation.AudioValidator(\n"
-            "    %(name)sDevice, %(channel)s,\n"
+            "    deviceManager.getDevice(%(deviceLabel)s), \n"
+            "    %(channel)s,\n"
             ")\n"
         )
         buff.writeIndentedLines(code % inits)
@@ -258,86 +203,5 @@ class AudioValidatorRoutine(BaseValidatorRoutine, PluginDevicesMixin):
         return stims
 
 
-class MicrophoneSoundSensorValidatorBackend(DeviceBackend):
-    """
-    Adds a microphone sound sensor emulation backend for AudioValidator, as well as acting as an
-    example for implementing other sound sensor device backends.
-    """
-
-    key = "microphone"
-    label = _translate("Microphone")
-    component = AudioValidatorRoutine
-    deviceClasses = ["psychopy.hardware.soundsensor.MicrophoneSoundSensor"]
-
-    def getParams(self: AudioValidatorRoutine):
-        # define order
-        order = [
-            'microphone',
-            'dbRange',
-            'samplingWindow'
-        ]
-        # define params
-        params = {}
-        def getDeviceIndices():
-            from psychopy.hardware.microphone import MicrophoneDevice
-            profiles = MicrophoneDevice.getAvailableDevices()
-
-            return [None] + [profile['index'] for profile in profiles]
-
-        def getDeviceNames():
-            from psychopy.hardware.microphone import MicrophoneDevice
-            profiles = MicrophoneDevice.getAvailableDevices()
-
-            return ["default"] + [profile['deviceName'] for profile in profiles]
-
-        params['microphone'] = Param(
-            None, valType='str', inputType="choice", categ="Device",
-            allowedVals=getDeviceIndices,
-            allowedLabels=getDeviceNames,
-            label=_translate("Microphone"),
-            hint=_translate(
-                "What microphone device to use?"
-            )
-        )
-        params['dbRange'] = Param(
-            (0, 1), valType="list", inputType="single", categ="Device",
-            label=_translate("Decibel range"),
-            hint=_translate(
-                "Range of possible decibels to expect mic responses to be in, by default (0, 1)"
-            )
-        )
-        params['samplingWindow'] = Param(
-            0.03, valType="code", inputType="single", categ="Device",
-            label=_translate("Sampling window"),
-            hint=_translate(
-                "How long (s) to average samples from the microphone across? Larger sampling "
-                "windows reduce the chance of random spikes, but also reduce sensitivity."
-            )
-        )
-
-        return params, order
-
-    def addRequirements(self):
-        # needs microphone
-        self.exp.requireImport(
-            importName="MicrophoneDevice",
-            importFrom="psychopy.hardware.microphone"
-        )
-
-    def writeDeviceCode(self: AudioValidatorRoutine, buff):
-        # get inits
-        inits = getInitVals(self.params)
-        # make MicrophoneVoiceKey object
-        code = (
-            "%(name)sDevice = MicrophoneDevice(\n"
-            "    index=%(microphone)s\n"
-            ")\n"
-            "deviceManager.addDevice(\n"
-            "    deviceClass='psychopy.hardware.soundsensor.MicrophoneSoundSensor',\n"
-            "    deviceName=%(deviceLabel)s,\n"
-            "    device=%(name)sDevice, \n"
-            "    dbRange=%(dbRange)s, \n"
-            "    samplingWindow=%(samplingWindow)s, \n"
-            ")\n"
-        )
-        buff.writeOnceIndentedLines(code % inits)
+from ...components.soundsensor import MicrophoneSoundSensorBackend
+AudioValidatorRoutine.registerBackend(MicrophoneSoundSensorBackend)