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

psychopy/experiment/devices.py

@@ -0,0 +1,303 @@
+import inspect
+from pathlib import Path
+from psychopy import logging
+from psychopy.experiment.params import Param
+from psychopy.localization import _translate
+
+
+class DeviceMixin:
+    """
+    Mixin for base Component/Routine classes which adds necessary params and attributes to 
+    interact with device manager. This shouldn't need to be mixed in directly - instead just use 
+    BaseDeviceComponent or BaseDeviceRoutine which include this mixin.
+    """
+    
+    def __init_subclass__(cls):
+        cls.backends = set()
+    
+    def addDeviceParams(self, defaultLabel=""):
+        from psychopy.preferences import prefs
+
+        # require hardware
+        self.exp.requirePsychopyLibs(
+            ['hardware']
+        )
+
+        # --- Device params ---
+        self.order += [
+            "deviceLabel"
+        ]
+        # functions for getting device labels
+        def getDevices():
+            # start with default
+            devices = [("", _translate("Default"))]
+            # iterate through saved devices
+            for name, device in prefs.devices.items():
+                # iterate through backends for this Component
+                for backend in self.backends:
+                    # if device is the correct type, include it
+                    if isinstance(device, backend):
+                        devices.append(
+                            (name, name)
+                        )
+            return devices
+        def getLabels():
+            return [device[1] for device in getDevices()]
+        def getValues():
+            return [device[0] for device in getDevices()]
+        # label to refer to device by
+        self.params['deviceLabel'] = Param(
+            defaultLabel, valType="device", inputType="device", categ="Device",
+            allowedVals=getValues,
+            allowedLabels=getLabels,
+            label=_translate("Device"),
+            hint=_translate(
+                "The named device from Device Manager to use for this Component."
+            )
+        )
+
+    @classmethod
+    def registerBackend(cls, backend):
+        """
+        Register a device backend as relevant to this Component.
+
+        Parameters
+        ----------
+        backend : type
+            Subclass of `psychopy.experiment.devices.DeviceBackend` to associate with this 
+            Component.
+        """
+        if not hasattr(cls, "backends"):
+            cls.backends = set()
+        
+        cls.backends.add(backend)
+
+
+class DeviceBackend:
+    """
+    Representation of a hardware class in Builder.
+    """
+    # name of this backend to display in Device Manager
+    backendLabel = None
+    # icon to use for this backend (relative to current file path, leave as None for no icon)
+    icon = None
+    # class of the device which this backend corresponds to
+    deviceClass = "psychopy.hardware.base.BaseDevice"
+      
+    def __init__(self, profile):
+        # store device profile
+        self.profile = profile
+        # initialise params and order arrays
+        self.params = {}
+        self.order = []
+        # add a param for the device label to all backends
+        self.params['deviceLabel'] = Param(
+            "", valType="str", inputType="name",
+            label=_translate("Device label"),
+            hint=_translate(
+                "A name to refer to this device by in Device Manager."
+            )
+        )
+        # device label always first
+        self.order += [
+            "deviceLabel"
+        ]
+        # get further params from subclass method
+        params, order = self.getParams()
+        self.params.update(params)
+        self.order += order
+    
+    def __repr__(self):
+        return (
+            f"<{type(self).__name__}: name={self.name}>"
+        )
+    
+    def getParams(self):
+        """
+        Get parameters from this backend to add to each new device from this backend.
+
+        Returns
+        -------
+        dict[str:Param]
+            Dict of Param objects for controlling devices in this backend
+        list[str]
+            List of param names, defining the order in which params should appear
+        """
+        return {}, []
+    
+    def writeDeviceCode(self, buff):
+        """
+        Write the code to create a device for this backend. This method must be overloaded by device backend subclasses.
+
+        To write the basics of device initialisation, you can do: ::
+            # this opens a call to DeviceManager.addDevice with the basic necessary arguments included, and does not close the brackets so you can add more
+            self.writeBaseDeviceCode(buff, close=False)
+            code = (
+                # write any param-specific inits here (e.g. "threshold=%(threshold)s,\n")
+                ")\n"
+            )
+            buff.writeIndentedLines
+        
+        To use just the basic device initialisation code, you can just do: ::
+            return self.writeBaseDeviceCode(buff, close=True)
+        """
+
+        raise NotImplementedError()
+
+    @classmethod
+    def getIconFile(cls):
+        """
+        Get the file for this backend's icon as a Path, if there is one
+
+        Returns
+        -------
+        Path or None
+            File path for this backend's icon, or None if there is no icon
+        """
+        # return None if no icon
+        if cls.icon is None:
+            return
+        # make sure it's a Path
+        icon = cls.icon
+        if isinstance(icon, str):
+            icon = Path(icon)
+        # get folder containing class def file
+        folder = Path(inspect.getfile(cls)).parent
+        # make absolute
+        file = (folder / icon).resolve()
+
+        return file
+    
+    @classmethod
+    def fromJSON(cls, data):
+        """
+        Initialise an instance of this class from a JSON dict.
+
+        Parameters
+        ----------
+        data : dict
+            JSON data to initialise from
+        """
+        # initialise
+        device = cls(
+            profile=data['profile']
+        )
+        # apply param vals
+        device.applyJSON(data)
+        
+        return device
+
+    def applyJSON(self, data):
+        """
+        Apply data from a JSON dict to this object.
+
+        Parameters
+        ----------
+        data : dict
+            JSON data to apply
+        """
+        # get profile
+        self.profile = data['profile']
+        # apply param vals
+        for name, val in data['params'].items():
+            self.params[name].applyJSON(val)
+    
+    def toJSON(self):
+        """
+        Get this object as a JSON dict.
+
+        Returns
+        -------
+        dict
+            JSON dict representing this object, will be in the form:..
+
+            {
+                '__cls__': <import string for this class>,
+                'profile': <dict from DeviceManager.getAvailableDevices>,
+                'params': <dict of Param JSON objects>,
+            }
+        """
+        # create dict
+        data = {
+            '__cls__': f"{type(self).__module__}.{type(self).__name__}",
+            'profile': self.profile,
+            'params': {}
+        }
+        # add params
+        for key, param in self.params.items():
+            data['params'][key] = param.toJSON()
+        
+        return data
+    
+    @staticmethod
+    def getAllBackends():
+        """
+        Get all backends known to the current PsychoPy session.
+
+        Returns
+        -------
+        list[type]
+            List of backend classes
+        """
+        from psychopy.experiment import getAllElements
+        from psychopy.experiment.monitor import BasePhotometerDeviceBackend, ScreenBufferPhotometerDeviceBackend
+        allBackends = []
+        # look for device backends associated with all known Components and Routines
+        for emt in getAllElements(fetchIcons=False).values():
+            if hasattr(emt, "backends"):
+                for backend in emt.backends:
+                    # check that each backend is a DeviceBackend
+                    if issubclass(backend, DeviceBackend) and backend not in allBackends:
+                        # append if so
+                        allBackends.append(backend)
+        # add subclasses of BasePhotometerBackend as it doesn't come from any Component
+        for cls in BasePhotometerDeviceBackend.__subclasses__():
+            if cls not in allBackends:
+                allBackends.append(cls)
+
+        return allBackends
+        
+    
+    def writeBaseDeviceCode(self, buff, close=False):
+        """
+        Write the basic device code
+
+        Parameters
+        ----------
+        buff : io.StringIO
+            Buffer to write to
+        close : bool, optional
+            If False (default), won't close the `addDevice` call (so you need to write the closing 
+            bracket yourself)
+        """
+        # write init call with device label
+        code = (
+            "# initialize %(deviceLabel)s\n"
+            "deviceManager.addDevice(\n"
+            "    deviceName=%(deviceLabel)s,\n"
+        )
+        buff.writeIndentedLines(code % self.params)
+        # add options from profile
+        code = ""
+        for key, value in self.profile.items():
+            # skip attributes already covered by a param
+            if key in self.params or key in ("deviceName", ):
+                continue
+            code += f"    {key}={repr(value)},\n"
+        buff.writeIndentedLines(code)
+        # if close requested, add closing bracket
+        if close:
+            code = (
+                ")\n"
+            )
+            buff.writeIndentedLines(code)
+      
+    @property
+    def name(self):
+        return self.params['deviceLabel'].val
+    
+    @name.setter
+    def name(self, value):
+        # update param value
+        self.params['deviceLabel'].val = value
+        

psychopy/experiment/exports.py

@@ -127,30 +127,31 @@ class NameSpace:
         2011 Jeremy Gray
     """
 
+    # numpy imports
+    numpy = _numpyImports + _numpyRandomImports + ['np']
+    # core python keywords
+    keywords = keyword.kwlist + dir(__builtins__) + ['self']
+    # builder stuff
+    builder = [
+        'KeyResponse', 'keyboard', 'buttons', 'continueRoutine', 'expInfo', 'expName', 'thisExp', 
+        'filename', 'logFile', 'paramName', 't', 'frameN', 'currentLoop', 'dlg', '_thisDir', 
+        'endExpNow', 'globalClock', 'routineTimer', 'frameDur', 'theseKeys', 'win', 'x', 'y', 
+        'level', 'component', 'thisComponent'
+    ]
+    # PsychoPy constants
+    constants = dir(constants)
+    # PsychoPy modules
+    psychopy = psychopy.__all__ + ['psychopy', 'os']
+    # all non-user builder stuff
+    nonUserBuilder = numpy + keywords + psychopy + constants
+    
     def __init__(self, exp):
         """Set-up an experiment's namespace: reserved words and user space
         """
         super(NameSpace, self).__init__()
         self.exp = exp
-        # deepcopy fails if you pre-compile regular expressions and stash here
-
-        self.numpy = _numpyImports + _numpyRandomImports + ['np']
-        # noinspection PyUnresolvedReferences
-        self.keywords = keyword.kwlist + dir(__builtins__) + ['self']
-        # these are based on a partial test, known to be incomplete:
-        self.psychopy = psychopy.__all__ + ['psychopy', 'os']
-        self.constants = dir(constants)
-        self.builder = ['KeyResponse', 'keyboard', 'buttons',
-                        'continueRoutine', 'expInfo', 'expName', 'thisExp',
-                        'filename', 'logFile', 'paramName',
-                        't', 'frameN', 'currentLoop', 'dlg', '_thisDir',
-                        'endExpNow',
-                        'globalClock', 'routineTimer', 'frameDur',
-                        'theseKeys', 'win', 'x', 'y', 'level', 'component',
-                        'thisComponent']
         # user-entered, from Builder dialog or conditions file:
         self.user = []
-        self.nonUserBuilder = self.numpy + self.keywords + self.psychopy
 
     def __str__(self, numpy_count_only=True):
         varibs = self.user + self.builder + self.psychopy
@@ -232,7 +233,8 @@ class NameSpace:
                        if i < len(su) - 1 and su[i + 1] == var]
         return duplicates or None
 
-    def isValid(self, name):
+    @staticmethod
+    def isValid(name):
         """var-name compatible? return True if string name is
         alphanumeric + underscore only, with non-digit first
         """

psychopy/experiment/flow.py

@@ -274,6 +274,11 @@ class Flow(list):
         code = (
             "# mark experiment as started\n"
             "thisExp.status = STARTED\n"
+            "# update experiment info\n"
+            "expInfo['date'] = data.getDateStr()\n"
+            "expInfo['expName'] = expName\n"
+            "expInfo['expVersion'] = expVersion\n"
+            "expInfo['psychopyVersion'] = psychopyVersion\n"
             "# make sure window is set to foreground to prevent losing focus\n"
             "win.winHandle.activate()\n"
             "# make sure variables created by exec are available globally\n"
@@ -336,6 +341,8 @@ class Flow(list):
                 "if ioServer is not None:\n"
                 "    ioServer.syncClock(globalClock)\n"
                 "logging.setDefaultClock(globalClock)\n"
+                "if eyetracker is not None:\n"
+                "    eyetracker.enableEventReporting()\n"
                 "# routine timer to track time remaining of each (possibly non-slip) routine\n"
                 "routineTimer = core.Clock()\n"
                 "win.flip()  # flip window to reset last flip timer\n"

psychopy/experiment/loops.py

@@ -93,7 +93,7 @@ class TrialHandler(_BaseLoopHandler):
         self.order = ['name']  # make name come first (others don't matter)
         self.params = {}
         self.params['name'] = Param(
-            name, valType='code', inputType="single", updates=None, allowedUpdates=None,
+            name, valType='code', inputType="name", updates=None, allowedUpdates=None,
             label=_translate('Name'),
             hint=_translate("Name of this loop"))
         self.params['nReps'] = Param(
@@ -107,7 +107,7 @@ class TrialHandler(_BaseLoopHandler):
             hint=_translate("A list of dictionaries describing the "
                             "parameters in each condition"))
         self.params['conditionsFile'] = Param(
-            conditionsFile, valType='file', inputType="table", updates=None, allowedUpdates=None,
+            conditionsFile, valType='file', inputType="conditions", updates=None, allowedUpdates=None,
             label=_translate('Conditions'),
             hint=_translate("Name of a file specifying the parameters for "
                             "each condition (.csv, .xlsx, or .pkl). Browse "
@@ -189,6 +189,7 @@ class TrialHandler(_BaseLoopHandler):
             "    originPath=-1, \n"
             "    trialList=%(trialList)s, \n"
             "    seed=%(random seed)s, \n"
+            "    isTrials=%(isTrials)s, \n"
             ")\n"
         )
         buff.writeIndentedLines(code % inits)
@@ -478,7 +479,7 @@ class StairHandler(_BaseLoopHandler):
         self.children = []
         self.params = {}
         self.params['name'] = Param(
-            name, valType='code',
+            name, valType='code', inputType="name",
             hint=_translate("Name of this loop"),
             label=_translate('Name'))
         self.params['nReps'] = Param(
@@ -560,15 +561,27 @@ class StairHandler(_BaseLoopHandler):
         if self.params['N reversals'].val in ("", None, 'None'):
             self.params['N reversals'].val = '0'
         # write the code
-        code = ('\n# --------Prepare to start Staircase "%(name)s" --------\n'
-                "# set up handler to look after next chosen value etc\n"
-                "%(name)s = data.StairHandler(startVal=%(start value)s, extraInfo=expInfo,\n"
-                "    stepSizes=%(step sizes)s, stepType=%(step type)s,\n"
-                "    nReversals=%(N reversals)s, nTrials=%(nReps)s, \n"
-                "    nUp=%(N up)s, nDown=%(N down)s,\n"
-                "    minVal=%(min value)s, maxVal=%(max value)s,\n"
-                "    originPath=-1, name='%(name)s')\n"
-                "thisExp.addLoop(%(name)s)  # add the loop to the experiment")
+        code = (
+            "\n"
+            "# --- Prepare to start Staircase '%(name)s' --- \n"
+            "# set up handler to look after next chosen value etc\n"
+            "%(name)s = data.StairHandler(\n"
+            "    startVal=%(start value)s, \n"
+            "    extraInfo=expInfo,\n"
+            "    stepSizes=%(step sizes)s, \n"
+            "    stepType=%(step type)s,\n"
+            "    nReversals=%(N reversals)s, \n"
+            "    nTrials=%(nReps)s, \n"
+            "    nUp=%(N up)s, \n"
+            "    nDown=%(N down)s,\n"
+            "    minVal=%(min value)s, \n"
+            "    maxVal=%(max value)s,\n"
+            "    originPath=-1, \n"
+            "    name='%(name)s',\n"
+            "    isTrials=%(isTrials)s, \n"
+            ")\n"
+            "thisExp.addLoop(%(name)s)  # add the loop to the experiment"
+        )
         buff.writeIndentedLines(code % self.params)
         code = "level = %s = %s  # initialise some vals\n"
         buff.writeIndented(code % (self.thisName, self.params['start value']))
@@ -633,7 +646,7 @@ class MultiStairHandler(_BaseLoopHandler):
         self.order = ['name']  # make name come first
         self.params = {}
         self.params['name'] = Param(
-            name, valType='code', inputType='single',
+            name, valType='code', inputType='name',
             label=_translate('Name'),
             hint=_translate("Name of this loop"))
         self.params['nReps'] = Param(
@@ -664,7 +677,7 @@ class MultiStairHandler(_BaseLoopHandler):
             hint=_translate('Where to loop from and to (see values currently'
                             ' shown in the flow view)'))
         self.params['conditions'] = Param(
-            list(conditions), valType='list', inputType='single',
+            list(conditions), valType='list', inputType='conditions',
             updates=None, allowedUpdates=None,
             label=_translate('Conditions'),
             hint=_translate("A list of dictionaries describing the "
@@ -692,7 +705,7 @@ class MultiStairHandler(_BaseLoopHandler):
                 return root / "staircaseTemplate.xltx"
 
         self.params['conditionsFile'] = Param(
-            conditionsFile, valType='file', inputType='table', updates=None, allowedUpdates=None,
+            conditionsFile, valType='file', inputType='conditions', updates=None, allowedUpdates=None,
             label=_translate('Conditions'),
             hint=_translate("An xlsx or csv file specifying the parameters "
                             "for each condition"),
@@ -718,20 +731,25 @@ class MultiStairHandler(_BaseLoopHandler):
         makeLoopIndex(self.params['name'].val)
         self.thisName = "condition"
         # create the MultistairHander
-        code = ("\n# set up handler to look after randomisation of trials etc\n"
-                "conditions = data.importConditions(%(conditionsFile)s)\n"
-                "%(name)s = data.MultiStairHandler(stairType=%(stairType)s, "
-                "name='%(name)s',\n"
-                "    nTrials=%(nReps)s,\n"
-                "    conditions=conditions,\n"
-                "    method=%(switchMethod)s,\n"
-                "    originPath=-1)\n"
-                "thisExp.addLoop(%(name)s)  # add the loop to the experiment\n"
-                "# initialise values for first condition\n"
-                "level = %(name)s._nextIntensity  # initialise some vals\n"
-                "condition = %(name)s.currentStaircase.condition\n"
-                # start the loop:
-                "\nfor level, condition in %(name)s:\n")
+        code = (
+            "\n# set up handler to look after randomisation of trials etc\n"
+            "conditions = data.importConditions(%(conditionsFile)s)\n"
+            "%(name)s = data.MultiStairHandler(\n"
+            "    stairType=%(stairType)s, "
+            "    name='%(name)s',\n"
+            "    nTrials=%(nReps)s,\n"
+            "    conditions=conditions,\n"
+            "    method=%(switchMethod)s,\n"
+            "    originPath=-1,\n"
+            "    isTrials=%(isTrials)s"
+            ")\n"
+            "thisExp.addLoop(%(name)s)  # add the loop to the experiment\n"
+            "# initialise values for first condition\n"
+            "level = %(name)s._nextIntensity  # initialise some vals\n"
+            "condition = %(name)s.currentStaircase.condition\n"
+            # start the loop:
+            "\nfor level, condition in %(name)s:\n"
+        )
         buff.writeIndentedLines(code % self.params)
 
         buff.setIndentLevel(1, relative=True)

psychopy/experiment/monitor.py

@@ -0,0 +1,74 @@
+from psychopy.experiment.devices import DeviceBackend
+from psychopy.experiment.params import Param
+from psychopy.experiment import getInitVals
+from psychopy.localization import _translate
+
+
+class BasePhotometerDeviceBackend(DeviceBackend):
+    """
+    Subclass common to all Photometer Device Backend classes, so they can be identified in the 
+    absence of a common Component.
+    """
+    icon = "../app/Resources/light/photometer.png"
+
+
+class ScreenBufferPhotometerDeviceBackend(BasePhotometerDeviceBackend):
+    """
+    Represents an emulator photometer, which just returns the pixel values from the screen for 
+    teaching / sanity checking purposes only.
+    """
+    backendLabel = "Photometer Emulator (debug)"
+    deviceClass = "psychopy.hardware.photometer.ScreenBufferPhotometerDevice"
+
+    def getParams(self):
+        params = {}
+        order = [
+            "pos",
+            "size",
+            "units"
+        ]
+
+        params['pos'] = Param(
+            (0, 0), valType="list", inputType="single",
+            label=_translate("Position (x, y)"),
+            hint=_translate(
+                "Position of the patch of pixels to pretend there is a photometer looking at"
+            )
+        )
+        params['size'] = Param(
+            (16, 16), valType="list", inputType="single",
+            label=_translate("Size (w, h)"),
+            hint=_translate(
+                "Size of the patch of pixels to pretend there is a photometer looking at"
+            )
+        )
+        params['units'] = Param(
+            "pix", valType="str", inputType="choice",
+            allowedVals=[
+                "from exp settings", "deg", "cm", "pix", "norm", "height", "degFlatPos", "degFlat"
+            ],
+            label=_translate("Spatial units"),
+            hint=_translate(
+                "Spatial units in which to interpret size and position"
+            )
+        )
+
+        return params, order
+    
+    def writeDeviceCode(self, buff):
+        # write core code
+        DeviceBackend.writeBaseDeviceCode(self, buff, close=False)
+        # get inits
+        inits = getInitVals(self.params)
+        # add params
+        code = (
+            "    win=win,\n"
+            "    size=%(size)s,\n"
+            "    pos=%(pos)s,\n"
+            "    units=%(units)s\n"
+            ")\n"
+        )
+        buff.writeIndentedLines(code % inits)
+
+
+