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

psychopy/hardware/joystick/__init__.py

@@ -1189,7 +1189,7 @@ def getAllJoysticks():
         joy = Joystick(joysticks[0]['index'])
 
     """
-    return Joystick.getAllJoysticks()
+    return Joystick.getAvailableDevices()
 
 
 if __name__ == "__main__":

psychopy/hardware/keyboard.py

@@ -456,14 +456,11 @@ class KeyboardDevice(BaseResponseDevice, aliases=["keyboard"]):
 
     @staticmethod
     def getAvailableDevices():
-        devices = []
-        for profile in st.getKeyboards():
-            devices.append({
-                'deviceName': profile.get('device_name', "Unknown Keyboard"),
-                'device': profile.get('index', -1),
-                'bufferSize': profile.get('bufferSize', 10000),
-            })
-        return devices
+        return [{
+            'deviceName': "Keyboard",
+            'device': -1,
+            'bufferSize': 10000
+        }]
 
     def getKeys(self, keyList=None, ignoreKeys=None, waitRelease=True, clear=True):
         """

psychopy/hardware/listener.py

@@ -274,7 +274,7 @@ class LoggingListener(BaseListener):
     level : int
         Logging level to log messages as, can be one of the constants from psychopy.logging. Default is logging.DEBUG.
     """
-    def __init__(self, file=logging.root, level=logging.DEBUG):
+    def __init__(self, file=logging.console, level=logging.DEBUG):
         # init base class
         BaseListener.__init__(self)
         # store params
@@ -287,7 +287,10 @@ class LoggingListener(BaseListener):
         """
         # append
         self.responses.append(message)
+        # log
         self.file.logger.log(message, level=self.level)
+        # flush log
+        logging.flush()
 
 
 class LiaisonListener(BaseListener):

psychopy/hardware/manager.py

@@ -152,6 +152,9 @@ class DeviceManager:
         if deviceClass in (None, "*"):
             # resolve "any" flags to BaseDevice
             deviceClass = "psychopy.hardware.base.BaseDevice"
+        # if it's already a type, return as is
+        if isinstance(deviceClass, type):
+            return deviceClass
         # get package and class names from deviceClass string
         parts = deviceClass.split(".")
         pkgName = ".".join(parts[:-1])
@@ -434,6 +437,52 @@ class DeviceManager:
         del DeviceManager.devices[deviceName]
 
         return True
+    
+    @staticmethod
+    def resolveDevice(device, deviceClass):
+        """
+        Resolve a value to a device, handling strings and using None to find/create a default 
+        device.
+
+        Parameters
+        ----------
+        device : any
+            Value to resolve
+        deviceClass : type or str
+            Class which the returned device should be an instance of (this can be a base class)
+        """
+        # resolve class
+        deviceClass = DeviceManager._resolveAlias(deviceClass)
+        # resolve device
+        if isinstance(device, deviceClass):
+            # if given a device directly, return it as is
+            return device
+        elif isinstance(device, str) and DeviceManager.hasDevice(device):
+            # if given the name of a managed device, get it
+            return DeviceManager.getDevice(device)
+        elif device is None:
+            # first try looking for extant devices
+            for cls in deviceClass.__subclasses__():
+                # add the first initialised device, if any
+                for thisDevice in DeviceManager.getInitialisedDevices(cls).values():
+                    return thisDevice
+            # if that fails, make one
+            for cls in deviceClass.__subclasses__():
+                # create a device from the first available profile
+                for profile in cls.getAvailableDevices():
+                    return cls(**{
+                        key: val for key, val in profile.items() if key not in ("deviceName", "deviceClass")
+                    })
+            # error if there are no available devices
+            raise DeviceNotConnectedError(
+                f"Could not find or create a default device for {deviceClass.__name__} as no "
+                f"devices are connected."
+            )
+        else:
+            raise ValueError(
+                f"Could not get device from '{device}', value is neither a {deviceClass.__name__} "
+                f"object or the name of one in DeviceManager."
+            )
 
     @staticmethod
     def getDevice(deviceName):
@@ -500,48 +549,15 @@ class DeviceManager:
         """
         from psychopy import experiment
 
-        # dict in which to store usages
         usages = {}
 
-        def _process(emt):
-            """
-            Process an element (Component or Routine) for device names and append them to the
-            usages dict.
-
-            Parameters
-            ----------
-            emt : Component or Routine
-                Element to process
-            """
-            # if we have a device name for this element...
-            if "deviceLabel" in emt.params:
-                # get init value so it lines up with boilerplate code
-                inits = experiment.getInitVals(emt.params)
-                # get value
-                deviceName = inits['deviceLabel'].val
-                # make sure device name is in usages dict
-                if deviceName not in usages:
-                    usages[deviceName] = []
-                # add any new usages
-                for cls in getattr(emt, "deviceClasses", []):
-                    if cls not in usages[deviceName]:
-                        usages[deviceName].append(cls)
-
         # process each experiment
         for file in experiments:
             # create experiment object
             exp = experiment.Experiment()
             exp.loadFromXML(file)
-
-            # iterate through routines
-            for rt in exp.routines.values():
-                if isinstance(rt, experiment.routines.BaseStandaloneRoutine):
-                    # for standalone routines, get device names from params
-                    _process(rt)
-                else:
-                    # for regular routines, get device names from each component
-                    for comp in rt:
-                        _process(comp)
+            # get info
+            usages.update(exp.getRequiredDeviceNames())
 
         return usages
 
@@ -641,6 +657,7 @@ class DeviceManager:
         """
         # if deviceClass is *, call for all types
         if deviceClass == "*":
+            DeviceManager.importAllComponentDeviceClasses()
             deviceClass = DeviceManager.deviceClasses
         # if given multiple types, call for each
         if isinstance(deviceClass, (list, tuple)):
@@ -782,6 +799,29 @@ class DeviceManager:
             device.clearListeners()
 
         return True
+    
+    @staticmethod
+    def importAllComponentDeviceClasses():
+        """
+        For all known Components, import the relevant device classes so they appear in 
+        DeviceManager.deviceClasses
+        """
+        from psychopy.experiment import getAllElements
+
+        # iterate through all detectable elements
+        for emt in getAllElements().values():
+            # if possible, get relevant device classes
+            if hasattr(emt, "backends"):
+                for cls in emt.backends:
+                    if hasattr(cls, "deviceClass"):
+                        # import it so we can detect it
+                        try:
+                            DeviceManager._resolveClassString(cls.deviceClass)
+                        except:
+                            logging.warn(
+                                f"Failed to load class {cls.deviceClass} from specification in "
+                                f"{cls.__name__} ({emt.__name__})"
+                            )
 
     @staticmethod
     def getResponseParams(deviceClass="*"):

psychopy/hardware/microphone.py

@@ -89,7 +89,7 @@ class MicrophoneDevice(BaseDevice, aliases=["mic", "microphone"]):
     Capture 10 seconds of audio from the primary microphone::
 
         import psychopy.core as core
-        import psychopy.sound.Microphone as Microphone
+        import psychopy.sound.microphone.Microphone as Microphone
 
         mic = Microphone(bufferSecs=10.0)  # open the microphone
         mic.start()  # start recording
@@ -275,6 +275,9 @@ class MicrophoneDevice(BaseDevice, aliases=["mic", "microphone"]):
         # recording buffer information
         self._recording = []  # use a list
         self._totalSamples = 0
+        self._absRecStartTime = self._absRecStopTime = -1.0
+        self._recPositionSecs = 0.0
+
         self._maxRecordingSize = (
             -1 if maxRecordingSize is None else int(maxRecordingSize))
         self._policyWhenFull = policyWhenFull
@@ -463,6 +466,7 @@ class MicrophoneDevice(BaseDevice, aliases=["mic", "microphone"]):
                 index = profile.get('index', None)
             device = {
                 'deviceName': profile.get('device_name', "Unknown Microphone"),
+                'deviceClass': "psychopy.hardware.microphone.MicrophoneDevice",
                 'index': index,
                 'sampleRateHz': profile.get('defaultSampleRate', None),
                 'channels': profile.get('inputChannels', None),
@@ -513,6 +517,16 @@ class MicrophoneDevice(BaseDevice, aliases=["mic", "microphone"]):
     def recBufferSecs(self):
         """Capacity of the recording buffer in seconds (`float`)."""
         return self._totalSamples / float(self._sampleRateHz)
+    
+    @property
+    def recSampleCount(self):
+        """Total number of samples in the recording buffer (`int`).
+
+        This is the total number of samples that have been recorded since the
+        last `start` call. If the stream is not started, this will return `0`.
+
+        """
+        return self._totalSamples
 
     @property
     def latencyBias(self):
@@ -642,6 +656,16 @@ class MicrophoneDevice(BaseDevice, aliases=["mic", "microphone"]):
             logging.debug(f"Microphone test failed. Error: {err}")
 
             raise err
+        
+    @property
+    def recordingTime(self):
+        """Current position in the recording buffer in seconds (`float`).
+
+        This is the position of the next sample to be written to the recording
+        buffer. If the stream is not started, this will return `0.0`.
+
+        """
+        return self._recPositionSecs
 
     def start(self, when=None, waitForStart=0, stopTime=None):
         """Start an audio recording.
@@ -679,11 +703,12 @@ class MicrophoneDevice(BaseDevice, aliases=["mic", "microphone"]):
         # reset the recording buffer
         self._recording = []
         self._totalSamples = 0
+        self._recPositionSecs = 0.0
 
         # reset warnings
         # self._warnedRecBufferFull = False
 
-        startTime = self._stream.start(
+        self._absRecStartTime = self._stream.start(
             repetitions=0,
             when=when,
             wait_for_start=int(waitForStart),
@@ -694,9 +719,9 @@ class MicrophoneDevice(BaseDevice, aliases=["mic", "microphone"]):
 
         logging.debug(
             'Scheduled start of audio capture for device #{} at t={}.'.format(
-                self._device.deviceIndex, startTime))
+                self._device.deviceIndex, self._absRecStartTime))
 
-        return startTime
+        return self._absRecStartTime
 
     def record(self, when=None, waitForStart=0, stopTime=None):
         """Start an audio recording (alias of `.start()`).
@@ -757,7 +782,7 @@ class MicrophoneDevice(BaseDevice, aliases=["mic", "microphone"]):
             return
 
         # poll remaining samples, if any
-        self.poll()
+        _ = self.poll()
 
         startTime, endPositionSecs, xruns, estStopTime = self._stream.stop(
             block_until_stopped=int(blockUntilStopped),
@@ -893,6 +918,16 @@ class MicrophoneDevice(BaseDevice, aliases=["mic", "microphone"]):
         if self._maxRecordingSize < 0:
             return False
         return self._totalSamples >= self._maxRecordingSize
+    
+    @property
+    def recStartTime(self):
+        """Absolute time when the recording started (`float`).
+
+        This is the time when the first sample was recorded. If the recording
+        has not started, this will be `-1.0`.
+
+        """
+        return self._absRecStartTime
 
     def poll(self):
         """Poll audio samples.
@@ -909,7 +944,14 @@ class MicrophoneDevice(BaseDevice, aliases=["mic", "microphone"]):
         Returns
         -------
         int
-            Number of overruns in sampling.
+            Current recording position in samples (`int`) and number of 
+            overflows (`int`). If the returned position is less than zero
+            (negative) then microphone is still starting up and wont be ready
+            until the position is greater than or equal to zero. If overflow 
+            occurs, this means that the recording buffer is full and no more 
+            samples can be added until polled. To prevent this, ensure that 
+            `poll()` is called often enough or increase the size of the audio 
+            buffer with `bufferSecs`.
 
         """
         if not self.isStarted:
@@ -975,8 +1017,12 @@ class MicrophoneDevice(BaseDevice, aliases=["mic", "microphone"]):
             elif self._policyWhenFull == 'error':
                 raise AudioStreamError(
                     "Recording buffer is full, no more samples will be added.")
+            
+        # update the recording position
+        self._absRecStopTime = absRecPosition / self._sampleRateHz
+        self._recPositionSecs = self._absRecStopTime - self._absRecStartTime
 
-        return 0
+        return absRecPosition, overflow
     
     def _mergeAudioFragments(self):
         """Merge audio fragments into a single segment.

psychopy/hardware/monitor.py

@@ -0,0 +1,144 @@
+from psychopy.monitors import Monitor, DACrange, GammaCalculator
+from psychopy.hardware import DeviceManager, keyboard
+import numpy as np
+import time
+
+__all__ = [
+    "Monitor",
+    "calibrateGamma"
+]
+
+
+def calibrateGamma(
+        win, 
+        photometer, 
+        patchSize=0.3, 
+        nPoints=8
+    ):
+    """
+    Use a photometer to calibrate the gamma for this monitor.
+
+    Parameters
+    ----------
+    win : psychopy.visual.Window
+        Window to run calibration in
+    photometer : str
+        Name of a photometer setup already in device manager
+    patchSize : float, optional
+        Size of the calibration patch as a proportion of the screen size (0-1), by default 0.3
+    nPoints : int, optional
+        Number of calibration points to use, by default 8
+    """
+    from psychopy import visual
+    from psychopy.hardware.photometer import BasePhotometerDevice
+
+    # get photometer device (if not given one)
+    if isinstance(photometer, BasePhotometerDevice):
+        phot = photometer
+    else:
+        phot = DeviceManager.getDevice(photometer)
+    # error if there isn't one
+    if phot is None:
+        raise ConnectionError(
+            "No photometer found. Try setting one up in the device manager."
+        )
+    # make sure nPoints is an integer
+    nPoints = int(nPoints)
+    # create a patch
+    patch = visual.GratingStim(
+        win,
+        tex="sqr",
+        size=(patchSize*2, patchSize*2),
+        units="norm",
+        rgb=(255, 255, 255),
+        colorSpace="rgb255",
+    )
+    # create instructions
+    instr = visual.TextBox2(
+        win,
+        text=(
+            "Point the photometer at the central box and press SPACE (or wait 2s) to "
+            "take a reading. Press ESCAPE to cancel."
+        ),
+        size=(2, 0.5),
+        pos=(0, 1),
+        padding=0.05,
+        anchor="top center",
+        alignment="top center",
+        letterHeight=0.05
+    )
+    # create progress indicator
+    prog = visual.TextBox2(
+        win,
+        text="Waiting for keypress...",
+        size=(1, 0.2),
+        pos=(-1, -1),
+        padding=0.05,
+        anchor="bottom left",
+        alignment="bottom left",
+        letterHeight=0.05
+    )
+    # do initial draw
+    win.flip()
+    patch.draw()
+    instr.draw()
+    prog.draw()
+    win.flip()
+    # this will hold the measured luminance values
+    lumSeries = np.zeros((4, nPoints), 'd')
+    # listen for keypress or 30s
+    kb = keyboard.Keyboard()
+    keys = kb.waitKeys(keyList=["escape", "space"], maxWait=30)
+    # abort if requested
+    if keys and "escape" in keys:
+        return
+    # clear instructions & update current action once responded
+    instr.text = ""
+    # iterate through levels
+    for lvl, dac in enumerate(DACrange(nPoints)):
+        # get relevant guns
+        if lvl == 0:
+            # guns are irrelevant when intensity is 0
+            guns = [None]
+        else:
+            guns = range(4)
+        # iterate through guns per level
+        for gun in guns:
+            # update progress indicator
+            prog.text = f"Level {lvl+1}/{nPoints}  Gun {gun+1 if gun is not None else 'NA'}/4"
+            # set the patch color
+            if gun in (0, None):
+                # if gun is 0 (aka luminance), set as flat
+                patch.color = dac
+            else:
+                # otherwise, set just the relevant gun and leave the rest black
+                patch.color = [
+                    dac if i == gun-1 else -1
+                    for i in range(3)
+                ]
+            # draw all & flip
+            patch.draw()
+            prog.draw()
+            win.flip()
+            # allow the screen to settle
+            time.sleep(0.2)
+            # take reading
+            lum = phot.getLum()
+            # if no gun, set for all
+            if gun is None:
+                for thisGun in range(4):
+                    lumSeries[thisGun, lvl] = lum
+            else:
+                lumSeries[gun, lvl] = lum
+    # transform lum series to a gamma grid
+    gammaGrid = []
+    for lumRow in lumSeries:
+        calc = GammaCalculator(
+            inputs=DACrange(nPoints),
+            lums=lumRow
+        )
+        gammaGrid.append(
+            [calc.min, calc.max, calc.gammaModel[0]]
+        )
+
+    return gammaGrid