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

psychopy/gui/qtgui.py

@@ -4,7 +4,7 @@
 # To build simple dialogues etc. (requires pyqt4)
 #
 #  Part of the PsychoPy library
-# Copyright (C) 2002-2018 Jonathan Peirce (C) 2019-2024 Open Science Tools Ltd.
+# Copyright (C) 2002-2018 Jonathan Peirce (C) 2019-2025 Open Science Tools Ltd.
 # Distributed under the terms of the GNU General Public License (GPL).
 import importlib
 from psychopy import logging, data
@@ -175,16 +175,25 @@ class Dlg(QtWidgets.QDialog):
 
         # set always stay on top
         if alwaysOnTop:
-            self.setWindowFlags(Qt.WindowType.WindowStaysOnTopHint)
+            if hasattr(Qt.WindowType, 'WindowStaysOnTopHint'):
+                self.setWindowFlags(Qt.WindowType.WindowStaysOnTopHint)
 
         # add buttons for OK and Cancel
-        buttons = QtWidgets.QDialogButtonBox.StandardButton.Ok | QtWidgets.QDialogButtonBox.StandardButton.Cancel
-        self.buttonBox = QtWidgets.QDialogButtonBox(buttons, parent=self)
+        if hasattr(QtWidgets.QDialogButtonBox.StandardButton, 'Ok'):
+            # PyQt6 upwards?
+            okBtn = QtWidgets.QDialogButtonBox.StandardButton.Ok
+            cancelBtn = QtWidgets.QDialogButtonBox.StandardButton.Cancel
+        else:
+            # e.g. PyQt5
+            okBtn = QtWidgets.QDialogButtonBox.Ok
+            cancelBtn = QtWidgets.QDialogButtonBox.Cancel
+            
+        self.buttonBox = QtWidgets.QDialogButtonBox(okBtn | cancelBtn, parent=self)
         self.buttonBox.accepted.connect(self.accept)
         self.buttonBox.rejected.connect(self.reject)
         # store references to OK and CANCEL buttons
-        self.okBtn = self.buttonBox.button(QtWidgets.QDialogButtonBox.StandardButton.Ok)
-        self.cancelBtn = self.buttonBox.button(QtWidgets.QDialogButtonBox.StandardButton.Cancel)
+        self.okBtn = self.buttonBox.button(okBtn)
+        self.cancelBtn = self.buttonBox.button(cancelBtn)
 
         if style:
             raise RuntimeWarning("Dlg does not currently support the "

psychopy/gui/wxgui.py

@@ -2,7 +2,7 @@
 # -*- coding: utf-8 -*-
 
 # Part of the PsychoPy library
-# Copyright (C) 2002-2018 Jonathan Peirce (C) 2019-2024 Open Science Tools Ltd.
+# Copyright (C) 2002-2018 Jonathan Peirce (C) 2019-2025 Open Science Tools Ltd.
 # Distributed under the terms of the GNU General Public License (GPL).
 
 """To build simple dialogues etc. (requires wxPython)

psychopy/hardware/__init__.py

@@ -5,7 +5,6 @@ import sys
 import glob
 from itertools import chain
 from psychopy import logging
-from . import eyetracker, listener
 from .manager import DeviceManager, deviceManager
 from .base import BaseDevice, BaseResponse, BaseResponseDevice
 

psychopy/hardware/base.py

@@ -5,7 +5,7 @@
 """
 
 # Part of the PsychoPy library
-# Copyright (C) 2002-2018 Jonathan Peirce (C) 2019-2024 Open Science Tools Ltd.
+# Copyright (C) 2002-2018 Jonathan Peirce (C) 2019-2025 Open Science Tools Ltd.
 # Distributed under the terms of the GNU General Public License (GPL).
 
 __all__ = [
@@ -14,7 +14,8 @@ __all__ = [
 
 import json
 import inspect
-import time
+import numpy as np
+from psychopy import logging
 
 
 class BaseResponse:
@@ -24,7 +25,8 @@ class BaseResponse:
     # list of fields known to be a part of this response type
     fields = ["t", "value"]
 
-    def __init__(self, t, value):
+    def __init__(self, t, value, device=None):
+        self.device = device
         self.t = t
         self.value = value
 
@@ -32,22 +34,50 @@ class BaseResponse:
         # make key=val strings
         attrs = []
         for key in self.fields:
-            attrs.append(f"{key}={getattr(self, key)}")
+            try:
+                attrs.append(f"{key}={getattr(self, key)}")
+            except:
+                continue
         attrs = ", ".join(attrs)
         # construct
-        return f"<{type(self).__name__}: {attrs}>"
+        try:
+            return f"<{type(self).__name__} from {self.getDeviceName()}: {attrs}>"
+        except:
+            return f"<{type(self).__name__}: {attrs}>"
+    
+    def getDeviceName(self):
+        # if device isn't a device, and this method isn't overloaded, return None
+        if not hasattr(self.device, "getDeviceProfile"):
+            return None
+        # get profile
+        deviceProfile = self.device.getDeviceProfile()
+        # get name from profile
+        if "deviceName" in deviceProfile:
+            return deviceProfile['deviceName']
+        else:
+            # if profile doesn't include name, use class name
+            return type(self.device).__name__
 
     def getJSON(self):
         import json
+        # get device profile
+        deviceProfile = None
+        if hasattr(self.device, "getDeviceProfile"):
+            deviceProfile = self.device.getDeviceProfile()
         # construct message as dict
         message = {
             'type': "hardware_response",
             'class': type(self).__name__,
+            'device': deviceProfile,
             'data': {}
         }
         # add all fields to "data"
         for key in self.fields:
             message['data'][key] = getattr(self, key)
+            # sanitize numpy arrays
+            if isinstance(message['data'][key], np.ndarray):
+                message['data'][key] = message['data'][key].tolist()
+
 
         return json.dumps(message)
 
@@ -56,6 +86,9 @@ class BaseDevice:
     """
     Base class for device interfaces, includes support for DeviceManager and adding listeners.
     """
+    # start off with no cached profile
+    _profile = None
+    
     def __init_subclass__(cls, aliases=None):
         from psychopy.hardware.manager import DeviceManager
         # handle no aliases
@@ -87,15 +120,20 @@ class BaseDevice:
         dict
             Dictionary representing this device
         """
-        # get class string
-        cls = type(self)
-        mro = inspect.getmodule(cls).__name__ + "." + cls.__name__
-        # iterate through available devices for this class
-        for profile in self.getAvailableDevices():
-            if self.isSameDevice(profile):
-                # if current profile is this device, add deviceClass and return it
-                profile['deviceClass'] = mro
-                return profile
+        # only iteratively find it if we haven't done so already
+        if self._profile is None:
+            # get class string
+            cls = type(self)
+            mro = inspect.getmodule(cls).__name__ + "." + cls.__name__
+            # iterate through available devices for this class
+            for profile in self.getAvailableDevices():
+                if self.isSameDevice(profile):
+                    # if current profile is this device, add deviceClass and return it
+                    profile['deviceClass'] = mro
+                    self._profile = profile
+                    break
+        
+        return self._profile
 
     def getJSON(self, asString=True):
         """
@@ -162,6 +200,8 @@ class BaseResponseDevice(BaseDevice):
         self.listeners = []
         # list to store responses in
         self.responses = []
+        # list to store callbacks against their triggering event
+        self.callbacks = []
         # indicator to mute outside of registered apps
         self.muteOutsidePsychopy = False 
 
@@ -186,6 +226,85 @@ class BaseResponseDevice(BaseDevice):
         raise NotImplementedError(
             "All subclasses of BaseDevice must implement the method `parseMessage`"
         )
+       
+    def registerCallback(self, response, func, args=None, kwargs=None):
+        """
+        Register a function to be executed automatically when this device receives a response with 
+        the matching value.
+
+        Parameters
+        ----------
+        response : *
+            Can be either:
+                - A value which will return True when compared via `==` to the desired response 
+                object, e.g. "q" to register a callback with KeyboardDevice when the q key is 
+                pressed
+                - A method which takes an incoming BaseResponse object as its input and returns 
+                True/False. Keep in mind this will be executed every time a response is received -
+                this function should be fast, otherwise you could significantly damage your timing!
+        func : function
+            Function to call when a matching response is received.
+        args : tuple, optional
+            List of positional arguments to call the function with, leave blank to give no 
+            positional arguments.
+        kwargs : dict, optional
+            Dict of keyword arguments to call the function with, leave blank to give no keyword 
+            arguments.
+        desc : str, optional
+            A helpful string describing what the callback does (e.g. "End the experiment")
+        """
+        
+        if callable(response):
+            # if response is callable, use it for query
+            query = response
+        else:
+            # otherwise, make a callable to check against incoming value
+            if self.responseClass.__eq__ is object.__eq__:
+                # warn if this device's responses aren't comparable via ==
+                logging.warn(
+                    "{clsName} received {respName} objects, which cannot be compared via `==`. "
+                    "This callback is likely to error when executed."
+                    .format(clsName=type(self).__name__, respName=self.responseClass.__name__)
+                )
+            # define a basic query and use it for the response query
+            def _callbackQuery(message: BaseResponse):
+                return message == response
+            query = _callbackQuery
+        # handle no args and no kwargs
+        if args is None:
+            args = []
+        if kwargs is None:
+            kwargs = {}
+        # store a dict profile for this callback
+        self.callbacks.append({
+            'query': query,
+            'func': func,
+            'args': args,
+            'kwargs': kwargs
+        })
+    
+    def clearCallbacks(self):
+        """
+        Un-register all callbacks which have been registered to this device by `registerCallback`
+        """
+        self.callbacks = []
+    
+    def checkCallbacks(self, message):
+        """
+        Check whether a received message should trigger any registered callback functions (see 
+        `.registerCallback`) and, if so, execute them.
+
+        Parameters
+        ----------
+        message : BaseResponse
+            Received response to query callbacks for
+        """
+        # check all registered callbacks
+        for callback in self.callbacks:
+            # call query function
+            if callback['query'](message):
+                # if True, execute callback
+                return callback['func'](*callback['args'], **callback['kwargs'])
 
     def receiveMessage(self, message):
         """
@@ -212,9 +331,20 @@ class BaseResponseDevice(BaseDevice):
         ).format(ownType=type(self).__name__, targetType=self.responseClass.__name__, msgType=type(message).__name__)
         # add message to responses
         self.responses.append(message)
+        # execute relevant callbacks
+        self.checkCallbacks(message)
         # relay message to listener
         for listener in self.listeners:
             listener.receiveMessage(message)
+        # relay to log file
+        try:
+            logging.exp(
+                f"Device response: {message}"
+            )
+        except Exception as err:
+            logging.error(
+                f"Received a response from a {type(self).__name__} but couldn't print it: {err}"
+            )
 
         return True
 
@@ -323,9 +453,10 @@ class BaseResponseDevice(BaseDevice):
         bool
             True if completed successfully
         """
-        # remove listeners from loop
+        # remove self from listener loop
         for listener in self.listeners:
-            listener.loop.removeDevice(listener)
+            if self in listener.loop.devices:
+                listener.loop.removeDevice(self)
         # clear list
         self.listeners = []
 

psychopy/hardware/bbtk/__init__.py

@@ -2,7 +2,7 @@
 # -*- coding: utf-8 -*-
 
 # Part of the PsychoPy library
-# Copyright (C) 2002-2018 Jonathan Peirce (C) 2019-2024 Open Science Tools Ltd.
+# Copyright (C) 2002-2018 Jonathan Peirce (C) 2019-2025 Open Science Tools Ltd.
 # Distributed under the terms of the GNU General Public License (GPL).
 
 """Interfaces for Black Box Toolkit Ltd. devices.
@@ -12,19 +12,13 @@ These are optional components that can be obtained by installing the
 
 """
 
-import psychopy.logging as logging
-
-try:
-    from psychopy_bbtk import BlackBoxToolkit
-except (ModuleNotFoundError, ImportError):
-    logging.error(
-        "Support for Black Box Toolkit hardware is not available this session. "
-        "Please install `psychopy-bbtk` and restart the session to enable "
-        "support.")
-except Exception as e:  # misc errors during module loading
-    logging.error(
-        "Error encountered while loading `psychopy-bbtk`. Check logs for more "
-        "information.")
-
-if __name__ == "__main__":
+
+from psychopy.plugins import PluginStub
+
+
+class BlackBoxToolkit(
+    PluginStub,
+    plugin="psychopy-iolabs",
+    docsHome="http://psychopy.github.io/psychopy-bbtk",
+):
     pass

psychopy/hardware/brainproducts.py

@@ -2,7 +2,7 @@
 # -*- coding: utf-8 -*-
 
 # Part of the PsychoPy library
-# Copyright (C) 2002-2018 Jonathan Peirce (C) 2019-2024 Open Science Tools Ltd.
+# Copyright (C) 2002-2018 Jonathan Peirce (C) 2019-2025 Open Science Tools Ltd.
 # Distributed under the terms of the GNU General Public License (GPL).
 
 """Interfaces for `Brain Products GMBH <https://www.brainproducts.com>`_
@@ -14,18 +14,12 @@ which allows you to control recordings, send annotations etc. all from Python.
 """
 
 import psychopy.logging as logging
+from psychopy.plugins import PluginStub
 
-try:
-    from psychopy_brainproducts import RemoteControlServer
-except (ModuleNotFoundError, ImportError):
-    logging.error(
-        "Support for Brain Products GMBH hardware is not available this "
-        "session. Please install `psychopy-brainproducts` and restart the "
-        "session to enable support.")
-except Exception as e:
-    logging.error(
-        "Error encountered while loading `psychopy-brainproducts`. Check logs "
-        "for more information.")
 
-if __name__ == "__main__":
+class RemoteControlServer(
+    PluginStub,
+    plugin="psychopy-brainproducts",
+    docsHome="https://psychopy.github.io/psychopy-brainproducts"
+):
     pass

psychopy/hardware/button.py

@@ -12,6 +12,25 @@ class ButtonResponse(base.BaseResponse):
         base.BaseResponse.__init__(self, t=t, value=value)
         # store channel
         self.channel = channel
+    
+    def __eq__(self, other):
+        """
+        ButtonResponse will recognise itself as equal to either:
+        - A boolean which matches its value
+        - An integer which matches its channel
+        - Another ButtonResponse which matches its value and channel
+        """
+        # match another ButtonResponse with the same value and channel
+        if isinstance(other, ButtonResponse):
+            return other.value == self.value and other.channel == self.channel
+        # match a boolean to response
+        if isinstance(other, bool):
+            return other == self.value
+        # match an integer to channel
+        if isinstance(other, int):
+            return other == self.channel
+        
+        return False
 
 
 class BaseButtonGroup(base.BaseResponseDevice):
@@ -140,7 +159,7 @@ class KeyboardButtonBox(BaseButtonGroup):
     def parseMessage(self, message):
         # work out time and state state of KeyPress
         state = message.duration is None
-        t = message.tDown
+        t = message.rt
         # if state is a release, add duration to timestamp
         if message.duration:
             t += message.duration
@@ -161,7 +180,7 @@ class KeyboardButtonBox(BaseButtonGroup):
 
     def isSameDevice(self, other):
         # all Keyboards are the same device
-        return True
+        return isinstance(other, (KeyboardButtonBox, dict))
 
 
 class ButtonBox:

psychopy/hardware/buttonbox/__init__.py

@@ -9,7 +9,7 @@ by calling the :func:`getAllButtonBoxes()` function.
 """
 
 # Part of the PsychoPy library
-# Copyright (C) 2002-2018 Jonathan Peirce (C) 2019-2024 Open Science Tools Ltd.
+# Copyright (C) 2002-2018 Jonathan Peirce (C) 2019-2025 Open Science Tools Ltd.
 # Distributed under the terms of the GNU General Public License (GPL).
 
 __all__ = [

psychopy/hardware/camera/__init__.py

@@ -8,7 +8,7 @@ experimenter to create movie stimuli or instructions.
 """
 
 # Part of the PsychoPy library
-# Copyright (C) 2002-2018 Jonathan Peirce (C) 2019-2024 Open Science Tools Ltd.
+# Copyright (C) 2002-2018 Jonathan Peirce (C) 2019-2025 Open Science Tools Ltd.
 # Distributed under the terms of the GNU General Public License (GPL).
 
 __all__ = [
@@ -2137,7 +2137,7 @@ class Camera:
     #     """
     #     pass
 
-    def record(self):
+    def record(self, clearLastRecording=True):
         """Start recording frames.
 
         This function will start recording frames and audio (if available). The
@@ -2152,7 +2152,16 @@ class Camera:
         Warnings
         --------
         If a recording has been previously made without calling `save()` it will
-        be discarded if `record()` is called again.
+        be discarded if `record()` is called again unless 
+        `clearLastRecording=False`.
+
+        Parameters
+        ----------
+        clearLastRecording : bool
+            Clear the frame buffer before starting the recording. If `True`,
+            the frame buffer will be cleared before starting the recording. If
+            `False`, the frame buffer will be kept and new frames will be added
+            to the buffer. Default is `True`.
 
         """
         if self.isNotStarted:
@@ -2162,6 +2171,10 @@ class Camera:
                 "opening now. This is not recommended as it may incur a longer "
                 "than expected delay in the recording start time."
             )
+
+        # clear previous frames
+        if clearLastRecording:
+            self._captureFrames.clear()
         
         self._audioTrack = None
         self._lastFrame = None

psychopy/hardware/cedrus.py

@@ -2,34 +2,23 @@
 # -*- coding: utf-8 -*-
 
 # Part of the PsychoPy library
-# Copyright (C) 2002-2018 Jonathan Peirce (C) 2019-2024 Open Science Tools Ltd.
+# Copyright (C) 2002-2018 Jonathan Peirce (C) 2019-2025 Open Science Tools Ltd.
 # Distributed under the terms of the GNU General Public License (GPL).
 
 """Interfaces for Cedrus Corporation devices such as button boxes.
 
 These are optional components that can be obtained by installing the
 `psychopy-cedrus` extension into the current environment.
-
-DEPRECATED:
-This sub-package is out of date. Please use the cedrus-written `pyxid2` package
-instead (bundled with Standalone PsychoPy)::
-
-    import pyxid2
-
 """
 
-import psychopy.logging as logging
-from psychopy.tools.pkgtools import PluginStub
+
+from psychopy.plugins import PluginStub
 
 
 class RB730(
     PluginStub, 
     plugin="psychopy-cedrus", 
-    doclink="https://psychopy.github.io/psychopy-cedrus/coder/RB730"
+    docsHome="https://psychopy.github.io/psychopy-cedrus",
+    docsRef="/coder/RB730"
 ):
     pass
-
-
-
-if __name__ == "__main__":
-    pass

psychopy/hardware/crs/__init__.py

@@ -2,7 +2,7 @@
 # -*- coding: utf-8 -*-
 
 # Part of the PsychoPy library
-# Copyright (C) 2002-2018 Jonathan Peirce (C) 2019-2024 Open Science Tools Ltd.
+# Copyright (C) 2002-2018 Jonathan Peirce (C) 2019-2025 Open Science Tools Ltd.
 # Distributed under the terms of the GNU General Public License (GPL).
 
 """Interfaces for Cambridge Research Systems hardware.

psychopy/hardware/crs/bits.py

@@ -1,34 +1,37 @@
-#!/usr/bin/env python
-# -*- coding: utf-8 -*-
-
-# Part of the PsychoPy library
-# Copyright (C) 2002-2018 Jonathan Peirce (C) 2019-2024 Open Science Tools Ltd.
-# Distributed under the terms of the GNU General Public License (GPL).
-
-# Acknowledgements:
-#    This code was initially written by Jon Peirce.
-#    with substantial additions by Andrew Schofield
-#    CRS Ltd provided support as needed.
-#    Shader code for mono++ and color++ modes was based on code in Psychtoolbox
-#    (Kleiner) but does not actually use that code directly
-
-import psychopy.logging as logging
-
-try:
-    from psychopy_crs.bits import (
-        BitsSharp,
-        BitsPlusPlus,
-        DisplayPlusPlus,
-        DisplayPlusPlusTouch)
-except (ModuleNotFoundError, ImportError):
-    logging.error(
-        "Support for Cambridge Research Systems Bits#, Bits++, Display++ and "
-        "Display++ Touch hardware is not available this session. Please "
-        "install `psychopy-crs` and restart the session to enable support.")
-except Exception as e:
-    logging.error(
-        "Error encountered while loading `psychopy-crs`. Check logs for more "
-        "information.")
-
-if __name__ == "__main__":
+from psychopy.plugins import PluginStub
+
+
+class BitsSharp(
+    PluginStub, 
+    plugin="psychopy-crs", 
+    docsHome="https://psychopy.github.io/psychopy-crs",
+    docsRef="/coder/bits/#psychopy_crs.bits.BitsSharp"
+):
+    pass
+
+
+class BitsPlusPlus(
+    PluginStub, 
+    plugin="psychopy-crs", 
+    docsHome="https://psychopy.github.io/psychopy-crs",
+    docsRef="/coder/bits/#psychopy_crs.bits.BitsPlusPlus"
+):
     pass
+
+
+class DisplayPlusPlus(
+    PluginStub, 
+    plugin="psychopy-crs", 
+    docsHome="https://psychopy.github.io/psychopy-crs",
+    docsRef="/coder/bits/#psychopy_crs.bits.DisplayPlusPlus"
+):
+    pass
+
+
+class DisplayPlusPlusTouch(
+    PluginStub, 
+    plugin="psychopy-crs", 
+    docsHome="https://psychopy.github.io/psychopy-crs",
+    docsRef="/coder/bits/#psychopy_crs.bits.DisplayPlusPlusTouch"
+):
+    pass

psychopy/hardware/crs/colorcal.py

@@ -2,20 +2,17 @@
 # -*- coding: utf-8 -*-
 
 # Part of the PsychoPy library
-# Copyright (C) 2002-2018 Jonathan Peirce (C) 2019-2024 Open Science Tools Ltd.
+# Copyright (C) 2002-2018 Jonathan Peirce (C) 2019-2025 Open Science Tools Ltd.
 # Distributed under the terms of the GNU General Public License (GPL).
 
 
-from psychopy.tools.pkgtools import PluginStub
+from psychopy.plugins import PluginStub
 
 
-class ColorCAL(PluginStub, plugin="psychopy-crs", doclink="https://psychopy.github.io/psychopy-crs/coder/ColorCAL"):
+class ColorCAL(
+    PluginStub, 
+    plugin="psychopy-crs", 
+    docsHome="https://psychopy.github.io/psychopy-crs",
+    docsRef="/coder/colorcal"
+):
     pass
-
-
-# Monkey-patch our metadata into CRS class if missing required attributes
-if not hasattr(ColorCAL, "longName"):
-    setattr(ColorCAL, "longName", "CRS ColorCAL")
-
-if not hasattr(ColorCAL, "driverFor"):
-    setattr(ColorCAL, "driverFor", ["colorcal"])

psychopy/hardware/crs/optical.py

@@ -21,16 +21,13 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 # THE SOFTWARE.
 
-from psychopy.tools.pkgtools import PluginStub
+from psychopy.plugins import PluginStub
 
 
-class OptiCAL(PluginStub, plugin="psychopy-crs", doclink="https://psychopy.github.io/psychopy-crs/coder/OptiCAL"):
+class OptiCAL(
+    PluginStub, 
+    plugin="psychopy-crs", 
+    docsHome="https://psychopy.github.io/psychopy-crs",
+    docsRef="/coder/optical"
+):
     pass
-
-
-# Monkey-patch our metadata into CRS class if missing required attributes
-if not hasattr(OptiCAL, "longName"):
-    setattr(OptiCAL, "longName", "CRS OptiCal")
-
-if not hasattr(OptiCAL, "driverFor"):
-    setattr(OptiCAL, "driverFor", ["optical"])