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

psychopy/sound/backend_sounddevice.py

@@ -8,25 +8,37 @@ These are optional components that can be obtained by installing the
 
 """
 
-import psychopy.logging as logging
-from .exceptions import DependencyError
-
-try:
-    from psychopy_sounddevice import (
-        SoundDeviceSound,
-        init,
-        getDevices,
-        getStreamLabel
-    )
-except (ModuleNotFoundError, ImportError):
-    logging.error(
-        "Support for the `sounddevice` audio backend is not available this "
-        "session. Please install `psychopy-sounddevice` and restart the "
-        "session to enable support.")
-except (NameError, DependencyError):
-    logging.error(
-        "Error encountered while loading `psychopy-sounddevice`. Check logs "
-        "for more information.")
-
-if __name__ == "__main__":
+
+from psychopy.plugins import PluginStub
+
+
+class SoundDeviceSound(
+    PluginStub,
+    plugin="psychopy-sounddevice",
+    docsHome="https://github.com/psychopy/psychopy-sounddevice",
+):
+    pass
+
+
+class init(
+    PluginStub,
+    plugin="psychopy-sounddevice",
+    docsHome="https://github.com/psychopy/psychopy-sounddevice",
+):
+    pass
+
+
+class getDevices(
+    PluginStub,
+    plugin="psychopy-sounddevice",
+    docsHome="https://github.com/psychopy/psychopy-sounddevice",
+):
+    pass
+
+
+class getStreamLabel(
+    PluginStub,
+    plugin="psychopy-sounddevice",
+    docsHome="https://github.com/psychopy/psychopy-sounddevice",
+):
     pass

psychopy/sound/exceptions.py

@@ -7,7 +7,7 @@
 from ..exceptions import SoundFormatError, DependencyError
 
 # 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/sound/microphone.py

@@ -5,14 +5,16 @@
 """
 
 # 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__ = ['Microphone']
 
 from pathlib import Path
+from psychopy import logging
 from psychopy.constants import NOT_STARTED
 from psychopy.hardware import DeviceManager
+from psychopy.tools.attributetools import logAttrib
 
 
 class Microphone:
@@ -24,11 +26,13 @@ class Microphone:
             streamBufferSecs=2.0,
             maxRecordingSize=24000,
             policyWhenFull='warn',
-            audioLatencyMode=None,
+            exclusive=False,
             audioRunMode=0,
             name="mic",
             recordingFolder=Path.home(),
             recordingExt="wav",
+            # legacy
+            audioLatencyMode=None,
     ):
         # store name
         self.name = name
@@ -53,9 +57,11 @@ class Microphone:
                 streamBufferSecs=streamBufferSecs,
                 maxRecordingSize=maxRecordingSize,
                 policyWhenFull=policyWhenFull,
-                audioLatencyMode=audioLatencyMode,
+                exclusive=exclusive,
                 audioRunMode=audioRunMode
             )
+        # set policy when full (in case device already existed)
+        self.device.policyWhenFull = policyWhenFull
         # setup clips and transcripts dicts
         self.clips = {}
         self.lastClip = None
@@ -66,6 +72,66 @@ class Microphone:
 
     def __del__(self):
         self.saveClips()
+    
+    @property
+    def maxRecordingSize(self):
+        """
+        Until a file is saved, the audio data from a Microphone needs to be stored in RAM. To avoid 
+        a memory leak, we limit the amount which can be stored by a single Microphone object. The 
+        `maxRecordingSize` parameter defines what this limit is.
+
+        Parameters
+        ----------
+        value : int
+            How much data (in kb) to allow, default is 24mb (so 24,000kb)
+        """
+        return self.device.maxRecordingSize
+    
+    @maxRecordingSize.setter
+    def maxRecordingSize(self, value):
+        # set size
+        self.device.maxRecordingSize = value
+    
+    def setMaxRecordingSize(self, value):
+        self.maxRecordingSize = value
+        # log
+        logAttrib(
+            obj=self, log=True, attrib="maxRecordingSize", value=value
+        )
+    setMaxRecordingSize.__doc__ == maxRecordingSize.__doc__
+
+    # the Builder param has a different name
+    setMaxSize = setMaxRecordingSize
+    
+    @property
+    def policyWhenFull(self):
+        """
+        Until a file is saved, the audio data from a Microphone needs to be stored in RAM. To avoid 
+        a memory leak, we limit the amount which can be stored by a single Microphone object. The 
+        `policyWhenFull` parameter tells the Microphone what to do when it's reached that limit.
+
+        Parameters
+        ----------
+        value : str
+            One of:
+            - "ignore": When full, just don't record any new samples
+            - "warn": Same as ignore, but will log a warning
+            - "error": When full, will raise an error
+            - "rolling": When full, clears the start of the buffer to make room for new samples
+        """
+        return self.device.policyWhenFull
+    
+    @policyWhenFull.setter
+    def policyWhenFull(self, value):
+        return self.device.policyWhenFull
+    
+    def setPolicyWhenFull(self, value):
+        self.policyWhenFull = value
+        # log
+        logAttrib(
+            obj=self, log=True, attrib="policyWhenFull", value=value
+        )
+    setPolicyWhenFull.__doc__ = policyWhenFull.__doc__
 
     @property
     def recording(self):
@@ -138,6 +204,9 @@ class Microphone:
     def close(self):
         return self.device.close()
 
+    def reopen(self):
+        return self.device.reopen()
+
     def poll(self):
         return self.device.poll()
 
@@ -152,6 +221,7 @@ class Microphone:
         """
         # iterate through all clips
         for tag in self.clips:
+            logging.info(f"Saving {len(self.clips[tag])} audio clips with tag {tag}")
             for i, clip in enumerate(self.clips[tag]):
                 # construct filename
                 filename = self.getClipFilename(tag, i)
@@ -213,8 +283,16 @@ class Microphone:
             self.scripts[tag] = []
 
         # append current recording to clip list according to tag
-        self.lastClip = self.getRecording()
-        self.clips[tag].append(self.lastClip)
+        lastClip = self.getRecording()
+        if lastClip is not None:
+            self.lastClip = lastClip
+            self.clips[tag].append(lastClip)
+        else:
+            # if no recording, return the correct number of items
+            if transcribe:
+                return None, None
+            else:
+                return None
 
         # synonymise null values
         nullVals = (

psychopy/sound/transcribe.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__ = [
@@ -1222,7 +1222,7 @@ def recognizeSphinx(audioClip=None, language='en-US', expectedWords=None,
     onlyInitialize = audioClip is None
     global _pocketSphinxTranscriber
     if _pocketSphinxTranscriber is None:
-        allTranscribers = getAllTranscribers(engineKeys=True)
+        allTranscribers = getAllTranscriberInterfaces(engineKeys=True)
         try:
             interface = allTranscribers['sphinx']
         except KeyError:
@@ -1297,7 +1297,7 @@ def recognizeGoogle(audioClip=None, language='en-US', expectedWords=None,
     onlyInitialize = audioClip is None
     global _googleCloudTranscriber
     if _googleCloudTranscriber is None:
-        allTranscribers = getAllTranscribers(engineKeys=True)
+        allTranscribers = getAllTranscriberInterfaces(engineKeys=True)
         try:
             interface = allTranscribers['googleCloud']
         except KeyError:

psychopy/tests/data/test_basic_run.py

@@ -0,0 +1 @@
+print("SUCCESS")

psychopy/tests/test_alerts/test_alerttools.py

@@ -1,5 +1,5 @@
 import sys
-from psychopy.alerts import alerttools
+from psychopy.alerts import addAlertHandler, alerttools
 from psychopy.alerts._errorHandler import _BaseErrorHandler
 from psychopy.experiment import getAllComponents, Experiment
 
@@ -10,6 +10,7 @@ class TestAlertTools():
     def setup_method(self):
         # Set ErrorHandler
         self.error = _BaseErrorHandler()
+        addAlertHandler(self.error)
 
         # Create experiment, trial, flow and test components
         self.exp = Experiment()

psychopy/tests/test_app/test_command_line.py

@@ -0,0 +1,65 @@
+"""
+Test that PsychoPy can be initialised from the command line with all API options
+"""
+import sys
+import time
+from pathlib import Path
+from psychopy import core
+from psychopy.tests import utils
+        
+
+def test_version_query():
+    """
+    Check that we can call the PsychoPy app with -v to get the version
+    """
+    from psychopy import __version__ as ppyVersion
+    cases = [
+        "-v",
+        "--version",
+    ]
+    for case in cases:
+        stderr = core.shellCall(
+            [sys.executable, "-m", "psychopy.app", case],
+            stderr=True
+        )
+        assert ppyVersion in "\n".join(stderr)
+
+
+def test_help_query():
+    """
+    Check that we can call the PsychoPy app with -h to get the help text
+    """
+    cases = [
+        "-h",
+        "--help",
+    ]
+    for case in cases:
+        stderr = core.shellCall(
+            [sys.executable, "-m", "psychopy.app", case],
+            stderr=True
+        )
+        assert "PsychoPy" in "\n".join(stderr)
+
+
+def test_direct_run():
+    """
+    Check that we can directly run files by invoking psychopy.app with -x
+    """
+    cases = [
+        {'tag': "-x", 'files': [str(Path(utils.TESTS_DATA_PATH) / "ghost_stroop.psyexp")]},
+        {'tag': "-x", 'files': [str(Path(utils.TESTS_DATA_PATH) / "test_basic_run.py")]},
+        {'tag': "-x", 'files': [
+            str(Path(utils.TESTS_DATA_PATH) / "ghost_stroop.psyexp"),
+            str(Path(utils.TESTS_DATA_PATH) / "test_basic_run.py")
+        ]},
+    ]
+    # include --direct too
+    for case in cases.copy():
+        case['tag'] = "--direct"
+        cases.append(case)
+    # run all cases
+    for case in cases:
+        stderr = core.shellCall(
+            [sys.executable, "-m", "psychopy.app", case['tag']] + case['files'],
+            stderr=True
+        )

psychopy/tests/test_data/test_TrialHandler2.py

@@ -296,6 +296,11 @@ class TestTrialHandler2:
                 t.skipTrials(case['advance'])
             else:
                 t.rewindTrials(case['advance'])
+            # account for current iteration ending (as if in experiment)
+            try:
+                t.__next__()
+            except StopIteration:
+                pass
             # get trials
             trials, i = t.getAllTrials()
             # make sure array is unchanged and i is as we expect
@@ -354,7 +359,7 @@ class TestTrialHandler2:
         cases = [
             # move backwards and forwards and check we land in the right place
             (+4, {'thisN': 4, 'thisRepN': 1, 'thisTrialN': 1, 'thisIndex': 1}),
-            (-1, {'thisN': 3, 'thisRepN': 1, 'thisTrialN': 0, 'thisIndex': 0}),
+            (-2, {'thisN': 2, 'thisRepN': 0, 'thisTrialN': 2, 'thisIndex': 2}),
             (-3, {'thisN': 0, 'thisRepN': 0, 'thisTrialN': 0, 'thisIndex': 0}),
             (+2, {'thisN': 2, 'thisRepN': 0, 'thisTrialN': 2, 'thisIndex': 2}),
             (-1, {'thisN': 1, 'thisRepN': 0, 'thisTrialN': 1, 'thisIndex': 1}),
@@ -365,19 +370,25 @@ class TestTrialHandler2:
             (+10, {'thisN': 5, 'thisRepN': 1, 'thisTrialN': 2, 'thisIndex': 2}),
         ]
         # iterate through cases
-        for inc, answer in cases:
+        for inc, answer in cases:           
             if inc < 0:
                 # if increment is negative, rewind
                 t.rewindTrials(inc)
             else:
                 # if positive, skip
                 t.skipTrials(inc)
+            # account for current iteration ending (as if in experiment)
+            try:
+                t.__next__()
+            except StopIteration:
+                pass
             # check that new current Trial is correct
-            for key in answer:
-                assert getattr(t.thisTrial, key) == answer[key], (
-                    f"Was expecting current trial to match all fields {answer}, instead was "
-                    f"{t.thisTrial.getDict()} (different {key})"
-                )
+            if t.thisTrial is not None:
+                for key in answer:
+                    assert getattr(t.thisTrial, key) == answer[key], (
+                        f"Was expecting current trial to match all fields {answer}, instead was "
+                        f"{t.thisTrial.getDict()} (different {key})"
+                    )
             # check that trials are still in the correct order
             if t.upcomingTrials:
                 assert t.upcomingTrials[0].thisN == t.thisTrial.thisN + 1

psychopy/tests/test_demos/test_builder_demos.py

@@ -42,7 +42,7 @@ def test_pilot_mode():
     # root Builder demos folder
     demosDir = Path(builder.__file__).parent
     # for all psyexp files in builder demos folder...
-    for file in demosDir.glob("**/*.psyexp"):
+    for file in demosDir.glob("*/*/*.psyexp"):
         # load experiment
         exp = experiment.Experiment.fromFile(file)
         # check piloting mode param