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

psychopy/hardware/photometer/__init__.py

@@ -18,151 +18,190 @@ __all__ = [
     'getAllPhotometerClasses'
 ]
 
+from psychopy.hardware.base import BaseResponseDevice, BaseResponse
+from psychopy import layout, logging
+
 from psychopy.plugins import PluginStub
 
-# Special handling for legacy classes which have been offloaded to optional
-# packages. This will change to allow more flexibility in the future to avoid
-# updating this package for additions to these sub-packages. We'll need a
-# photometer type to do that, but for now we're doing it like this.
-from psychopy.hardware.crs.colorcal import ColorCAL
-from psychopy.hardware.crs.optical import OptiCAL
 
-# Photo Resaerch Inc. spectroradiometers
-from psychopy.hardware.pr import PR655, PR650
+class PhotometerResponse(BaseResponse):
+    """
+    Response from a photometer device. Value can be a single integer, could represent overall 
+    luminance or the value of a single gun.
+    """
+    pass
 
-# Konica Minolta light-measuring devices
-from psychopy.hardware.minolta import LS100, CS100A
 
-# Gamma scientific devices
-from psychopy.hardware.gammasci import S470
+class BasePhotometerDevice(BaseResponseDevice):
+    responseClass = PhotometerResponse
 
-# photometer interfaces will be stored here after being registered
-photometerInterfaces = {}
+    def getLum(self):
+        """
+        Get luminance according to pixel values.
+        """
+        # dispatch messages and return the most recent
+        self.dispatchMessages()
+        if self.responses:
+            resp = self.responses[-1]
+            return resp.value
+        else:
+            # if no messages, assume no luminance
+            return 0
 
 
-def addPhotometer(cls):
-    """Register a photometer interface class.
+class ScreenBufferPhotometerDevice(BasePhotometerDevice):
+    """
+    Samples pixel colors from the screen buffer to emulate a photometer. Useful only for teaching, 
+    as the output will always behave as if the screen is perfectly calibrated, as there's no 
+    physical measurement involved.
+
+    Parameters
+    ----------
+    win : psychopy.visual.Window
+        Window to pull pixel values from
+    pos : tuple, list
+        Position of the patch of pixels to pretend there is a photometer looking at
+    size : tuple, list
+        Size of the patch of pixels to pretend there is a photometer looking at
+    units : str
+        "Spatial units in which to interpret size and position"
+    """
+    def __init__(self, win, pos=None, size=None, units=None):
+        # initialize
+        BaseResponseDevice.__init__(self)
+            # store win
+        self.win = win
+        # default rect
+        self.rect = None
+        # make clock
+        from psychopy.core import Clock
+        self.clock = Clock()
+        # store position params
+        self.units = units
+        self.pos = pos
+        self.size = size
+    
+    @property
+    def pos(self):
+        return getattr(self._pos, self.units)
+    
+    @pos.setter
+    def pos(self, value):
+        self._pos = layout.Position(value, units=self.units, win=self.win)
+    
+    @property
+    def size(self):
+        return getattr(self._size, self.units)
+    
+    @size.setter
+    def size(self, value):
+        self._size = layout.Size(value, units=self.units, win=self.win)
+
+    def dispatchMessages(self):
+        """
+        When called, dispatch a single reading.
+        """
+        # get rect
+        left, bottom = self._pos.pix + self.win.size / 2
+        w, h = self._size.pix
+        left = int(left - w / 2)
+        bottom = int(bottom - h / 2)
+        w = int(w)
+        h = int(h)
+        # read front buffer luminances for specified area
+        pixels = self.win._getPixels(
+            buffer="front",
+            rect=(left, bottom, w, h),
+            makeLum=True
+        )
+        # dispatch a message
+        self.receiveMessage(
+            self.parseMessage(pixels.mean() / 255)
+        )
+
+    def parseMessage(self, message):
+        return PhotometerResponse(
+            t=self.clock.getTime(),
+            value=message,
+            device=self
+        )
+
+    def isSameDevice(self, other):
+        return isinstance(other, ScreenBufferPhotometerDevice)
+    
+    @staticmethod
+    def getAvailableDevices():
+        # there's only ever one
+        return [{
+            'deviceName': "Photometer Emulator",
+            'deviceClass': "psychopy.hardware.photometer.ScreenBufferPhotometerDevice",
+            'win': "session.win",
+        }]
+
+
+# --- legacy methods ---
 
-    Once a photometer class is registered, it will be discoverable when
-    :func:`getAllPhotometers()` is called. This function is also used by the
-    plugin interface to add new interfaces at runtime.
 
-    This function will overwrite interface with the same `driverFor` name
-    automatically.
+def addPhotometer(cls):
+    """
+    DEPRECATED: Photometer classes are added on import, so this function is no longer needed.
 
     Parameters
     ----------
     cls : Any
         Class specifying a photometer interface.
-
     """
-    global photometerInterfaces
-
-    # photometers interfaces are IDed by the model they interface with
-    if not hasattr(cls, 'driverFor') or cls.driverFor is None:
-        raise AttributeError(
-            "Photometer interface class does not define member `driverFor` and "
-            "cannot be added.")
-
-    # add interface references to dictionary
-    if isinstance(cls.driverFor, (list, tuple)):
-        # multiple devices sharing the same interface
-        for devModel in cls.driverFor:
-            if not isinstance(devModel, str):  # items must be all strings
-                raise TypeError(
-                    "Invalid item type for array `driverFor`. Items must all "
-                    "have type `str`.")
-            photometerInterfaces[devModel] = cls
-    elif isinstance(cls.driverFor, str):
-        devModel = cls.driverFor
-        photometerInterfaces[devModel] = cls
-    else:
-        raise TypeError(
-            "Invalid type for `driverFor` member specified. Must be either "
-            "`str`, `tuple` or `list`.")
+    logging.warning(
+        "`addPhotometer` is deprecated, photometer classes are added on import so this function "
+        "is not needed."
+    )
 
 
 def getAllPhotometers():
-    """Gets all available photometers.
-
-    The returned photometers may vary depending on which drivers are installed.
-    Standalone PsychoPy ships with libraries for all supported photometers.
+    """
+    Legacy method to get available photometers. Will return subclasses of BasePhotometerDevice as 
+    well as legacy handlers for previously supported devices.
 
     Returns
     -------
     dict
-        A mapping of all photometer classes. Where the keys (`str`) are model
-        names the interface works with and the values are references to the
-        unbound interface class associated with it. Keys can have the same value
-        the interface is common to multiple devices.
-
+        Device classes against the names by which to represent them.
     """
-    # Given that we need to preserve legacy namespaces for the time being, we
-    # need to import supported photometer classes from their extant namespaces.
-    # In the future, all photometer classes will be identified by possessing a
-    # common base class and being a member of this module. This is much like
-    # how Builder components are discovered.
-
-    # build a dictionary with names
-    foundPhotometers = {}
-
-    # Classes from extant namespaces. Even though these are optional, we need
-    # to respect the namespaces for now.
-    optionalPhotometers = (
-        'ColorCAL', 'OptiCAL', 'S470', 'PR650', 'PR655', 'LS100', 'CS100A')
-    incPhotomList = []
-    for photName in optionalPhotometers:
-        try:
-            photClass = globals()[photName]
-        except (ImportError, AttributeError):
-            continue
-        if issubclass(photClass, PluginStub):
-            continue
-        incPhotomList.append(photClass)
-
-    # iterate over all classes and register them as if they were plugins
-    for photom in incPhotomList:
-        addPhotometer(photom)
-
-    # Merge with classes from plugins. Duplicate names will be overwritten by
-    # the plugins.
-    foundPhotometers.update(photometerInterfaces)
-
-    return foundPhotometers.copy()
+    # get photometer classes the new way: by looking for subclasses of BasePhotometerDevice
+    found = BasePhotometerDevice.__subclasses__()
+    # import classes which used to be in PsychoPy
+    from psychopy.hardware.crs.colorcal import ColorCAL
+    from psychopy.hardware.crs.optical import OptiCAL
+    from psychopy.hardware.pr import PR655, PR650
+    from psychopy.hardware.minolta import LS100, CS100A
+    from psychopy.hardware.gammasci import S470
+    # include any which aren't PluginStub's
+    for cls in (
+        ColorCAL,
+        OptiCAL,
+        PR655, 
+        PR650,
+        LS100, 
+        CS100A,
+        S470
+    ):
+        if not issubclass(cls, PluginStub):
+            found.append(cls)
+
+    return {
+        cls.__name__: cls
+        for cls in found
+    }
 
 
 def getAllPhotometerClasses():
-    """Get unique photometer interface classes presently available.
-
-    This is used to preserve compatibility with the legacy
-    :func:`~psychopy.hardware.getAllPhotometers()` function call.
+    """
+    Legacy method to get available photometers. Will return subclasses of BasePhotometerDevice as 
+    well as legacy handlers for previously supported devices.
 
     Returns
     -------
-    list
-        Discovered unique photometer classes.
-
+    dict
+        Device classes against the names by which to represent them.
     """
-    # iterate over known photometers
-    photometers = getAllPhotometers()
-
-    if not photometers:  # do nothing if no photometers found
-        return []
-
-    interfaceIDs = []  # a store unique IDs for interfaces
-    # Remove items the are duplicated, i.e. multiple IDs that have a common
-    # interface.
-    knownInterfaces = []
-    for cls in photometers.values():
-        clsID = id(cls)
-        if clsID in interfaceIDs:  # already added
-            continue
-
-        interfaceIDs.append(clsID)
-        knownInterfaces.append(cls)
-
-    return knownInterfaces
-
-
-if __name__ == "__main__":
-    pass
+    return getAllPhotometers()

psychopy/hardware/serialdevice.py

@@ -293,7 +293,21 @@ class SerialDevice(BaseDevice, AttributeGetSetMixin):
             t = time.time() - start
             resp = self.com.read()
         # get remaining chars
-        resp += self.com.readall()
+        active = True
+        while active and t < timeout:
+            # get resp
+            thisResp = self.com.read_until(self.eol)
+            # concatenate it to what we already have
+            resp += thisResp
+            # decide whether to continue
+            if thisResp.endswith(self.eol) and not multiline:
+                # in single line mode, always stop after an eol
+                active = False
+            else:
+                # otherwise, continue so long as we have a response
+                active = len(thisResp)
+            # wait for more
+            self.pause()
         # if we timed out, return None
         if t > timeout:
             return
@@ -301,7 +315,7 @@ class SerialDevice(BaseDevice, AttributeGetSetMixin):
         resp = resp.decode('utf-8')
         # if multiline, split by eol
         if multiline:
-            resp = resp.split(str(self.eol))
+            resp = resp.split(self.eol.decode("utf-8"))
 
         return resp
 

psychopy/hardware/soundsensor.py

@@ -346,6 +346,9 @@ class MicrophoneSoundSensor(BaseSoundSensorGroup):
             self.getThreshold(channel=channel) * (max(self.dbRange) - min(self.dbRange))
         )
     
+    def getCurrentVolume(self):
+        return self.device.getCurrentVolume()
+    
     def _setThreshold(self, threshold, channel=None):
         """
         No additional setup is needed for emulator as thresholding is emulated outside of the 
@@ -367,7 +370,7 @@ class MicrophoneSoundSensor(BaseSoundSensorGroup):
             vol = max(vol)
         # transform volume to arbitrary units
         adjVol = int(
-            (vol - min(self.dbRange)) / (max(self.dbRange) - min(self.dbRange)) * 255
+            (vol - min(self.dbRange)) / (max(self.dbRange) - min(self.dbRange))
         )
         # iterate through channels
         for channel in range(self.channels):

psychopy/iohub/devices/deviceConfigValidation.py

@@ -490,7 +490,8 @@ def validateDeviceConfiguration(
     """Validate the device configuration settings provided.
     """
     validation_module = importDeviceModule(relative_module_path)
-    validation_file_path = getSupportedConfigSettings(validation_module)
+    validation_file_path = getSupportedConfigSettings(
+        validation_module, deviceClassName=device_class_name)
 
     # use a default config if we can't get the YAML file
     if not os.path.exists(validation_file_path):

psychopy/iohub/devices/eyetracker/hw/gazepoint/__init__.py

@@ -9,6 +9,7 @@ try:
     from psychopy_eyetracker_gazepoint.gazepoint.gp3 import (
         __file__,
         EyeTracker, 
+        GazepointSampleEvent,
         MonocularEyeSampleEvent,
         BinocularEyeSampleEvent, 
         FixationStartEvent,
@@ -16,8 +17,7 @@ try:
         SaccadeStartEvent,
         SaccadeEndEvent, 
         BlinkStartEvent,
-        BlinkEndEvent,
-        GazepointSampleEvent
+        BlinkEndEvent
     )
 except (ModuleNotFoundError, ImportError, NameError):
     logging.error(

psychopy/iohub/devices/eyetracker/hw/gazepoint/gp3/__init__.py

@@ -9,6 +9,7 @@ try:
     from psychopy_eyetracker_gazepoint.gazepoint.gp3 import (
         __file__,
         EyeTracker, 
+        GazepointSampleEvent,
         MonocularEyeSampleEvent,
         BinocularEyeSampleEvent, 
         FixationStartEvent,

psychopy/iohub/devices/eyetracker/hw/gazepoint/gp3/eyetracker.py

@@ -17,5 +17,15 @@ except (ModuleNotFoundError, ImportError, NameError):
         "'psychopy-eyetracker-gazepoint' to be installed. Please install this "
         "package and restart the session to enable support.")
 
+# sample event for this device was moved to the plugin, but we're going to use
+# the original class for compatibility with older plugin versions
+try:
+    from psychopy_eyetracker_gazepoint.gazepoint.gp3.eyetracker import (
+        GazepointSampleEvent)
+except (ModuleNotFoundError, ImportError, NameError):
+    # import it from the old iohub location
+    from ....eye_events import GazepointSampleEvent
+
+
 if __name__ == "__main__":
     pass

psychopy/iohub/devices/keyboard/darwin.py

@@ -11,6 +11,7 @@ from .. import Computer, Device
 
 #>>>>>>>>>>>>>>>>>>>>>>>>
 
+import sys
 import ctypes
 import ctypes.util
 import CoreFoundation
@@ -47,13 +48,10 @@ psychopy_numlock_key_mappings['.'] = 'num_decimal'
 carbon_path = ctypes.util.find_library('Carbon')
 carbon = ctypes.cdll.LoadLibrary(carbon_path)
 
-_objc = ctypes.PyDLL(objc._objc.__file__)
-_objc.PyObjCObject_New.restype = ctypes.py_object
-_objc.PyObjCObject_New.argtypes = [ctypes.c_void_p, ctypes.c_int, ctypes.c_int]
-
 
 def objcify(ptr):
-    return _objc.PyObjCObject_New(ptr, 0, 1)
+    return objc.objc_object(c_void_p=ptr)
+
 
 kTISPropertyUnicodeKeyLayoutData_p = ctypes.c_void_p.in_dll(
     carbon, 'kTISPropertyUnicodeKeyLayoutData')
@@ -123,6 +121,11 @@ modifier_name_mappings = dict(
 
 
 class Keyboard(ioHubKeyboardDevice):
+    """Keyboard device class for iohub on Mac OS X using Quartz.
+    
+    This class uses the Quartz API to monitor keyboard events on Mac OS X.    
+
+    """
     _last_mod_names = []
     _OS_MODIFIERS = ([(0x00001, 'lctrl'), (0x02000, 'rctrl'),
                       (0x00002, 'lshift'), (0x00004, 'rshift'),

psychopy/iohub/util/__init__.py

@@ -168,14 +168,13 @@ def getSupportedConfigSettings(moduleName, deviceClassName=None):
         fileName = 'supported_config_settings_{0}.yaml'.format(
             deviceClassName.lower())
         yamlFile = yamlRoot / pathlib.Path(moduleName.__file__).parent / fileName
-        if not yamlFile.exists():
-            raise FileNotFoundError(
-                "No config file found in module dir for: {0}".format(
-                    moduleName))
-        logging.debug(
-            "Found ioHub device configuration file: {0}".format(yamlFile))
-
-        return str(yamlFile)
+        if yamlFile.exists():
+            logging.debug(
+                "Found ioHub device configuration file: {0}".format(yamlFile))
+            return str(yamlFile)
+        logging.debug(("No configuration matching device class name '{0}' found in "
+                       "module dir {1}. Using default config file instead.").format(
+            deviceClassName, yamlRoot))
 
     # file name for yaml file name convention for single file
     yamlFile = yamlRoot / pathlib.Path('supported_config_settings.yaml')