CreativePython 1.1.6__tar.gz → 1.2__tar.gz

{creativepython-1.1.6/src/CreativePython.egg-info → creativepython-1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: CreativePython
-Version: 1.1.6
+Version: 1.2
 Summary: A Python-based software environment for developing algorithmic art projects.
 Author-email: "Dr. Bill Manaris" <manaris@cofc.edu>, Taj Ballinger <ballingertj@g.cofc.edu>, Trevor Ritchie <ritchiets@g.cofc.edu>
 License: MIT License

{creativepython-1.1.6 → creativepython-1.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "CreativePython"
-version = "1.1.6"
+version = "1.2"
 description = "A Python-based software environment for developing algorithmic art projects."
 readme = "README.md"
 license = { file = "LICENSE" }
@@ -40,7 +40,7 @@ dependencies = [
 
 [tool.setuptools]
 package-dir = {"" = "src"}
-py-modules = ["gui", "image", "midi", "music", "osc", "timer", "iannix", "markov", "zipf"]
+py-modules = ["gui", "image", "midi", "music", "osc", "timer", "animation", "iannix", "markov", "zipf"]
 
 [tool.setuptools.packages.find]
 where = ["src"]

{creativepython-1.1.6 → creativepython-1.2}/src/CreativePython/GuiRenderer.py

@@ -997,8 +997,6 @@ class DisplayMirror:
          else:
             item.qObject.setZValue(qZValue)
             self._scene.addItem(item.qObject)      # attach QGraphicsItem to scene
-            cacheMode = QtWidgets.QGraphicsItem.CacheMode.DeviceCoordinateCache
-            item.qObject.setCacheMode(cacheMode)
 
          posArgs = {}
          if x is not None:
@@ -2874,9 +2872,6 @@ class GroupMirror(_DrawableMirror):
       item.qObject.setZValue(qZValue)
       self.qObject.addToGroup(item.qObject)
 
-      cacheMode = QtWidgets.QGraphicsItem.CacheMode.DeviceCoordinateCache
-      item.qObject.setCacheMode(cacheMode)
-
    def _removeChild(self, args, responseId):
       """Removes a child from the group."""
       itemId = args.get('itemId')

{creativepython-1.1.6 → creativepython-1.2}/src/CreativePython/RealtimeAudioPlayer.py

@@ -306,9 +306,9 @@ class _RealtimeAudioPlayer:
       self.loopRegionStartFrame = max(0.0, float(loopRegionStartFrame))
       self.loopRegionEndFrame = float(loopRegionEndFrame) if loopRegionEndFrame is not None else -1.0
 
-      # adjust the loop region end frame so it does not exceed the last valid frame in the audio file
+      # adjust the loop region end frame so it does not exceed the end of the audio file
       if self.loopRegionEndFrame > 0:
-         self.loopRegionEndFrame = min(self.loopRegionEndFrame, self.numFrames - 1 if self.numFrames > 0 else 0.0)
+         self.loopRegionEndFrame = min(self.loopRegionEndFrame, float(self.numFrames))
 
       # ensure the loop region is valid: if the start frame is after or equal to the end frame, reset to default (full file)
       if self.numFrames > 0 and self.loopRegionEndFrame > 0 and self.loopRegionStartFrame >= self.loopRegionEndFrame:
@@ -689,7 +689,8 @@ class _RealtimeAudioPlayer:
 
       # determine where playback should end for this segment
       # NOTE: supports three modes: natural EOF, loop region end, or play(size) duration
-      effectiveSegmentEndFrame = numAudioFrames - 1
+      # effectiveSegmentEndFrame is the exclusive end (first frame NOT to play)
+      effectiveSegmentEndFrame = float(numAudioFrames)
       if looping and self.loopRegionEndFrame > 0:
          effectiveSegmentEndFrame = self.loopRegionEndFrame
       elif not looping and self.targetEndSourceFrame > 0:
@@ -699,14 +700,13 @@ class _RealtimeAudioPlayer:
       # NOTE: batch boundary detection avoids per-sample checks (major optimization)
       framesToProcess = frames
       willHitBoundary = False
-      boundaryFrame = -1
 
       if effectiveSegmentEndFrame > 0:
          framesToEndpoint = (effectiveSegmentEndFrame - self.playbackPosition) / rateFactor
-         if framesToEndpoint < frames and framesToEndpoint > 0:
+         if 0 <= framesToEndpoint < frames:
             willHitBoundary = True
-            boundaryFrame = int(np.floor(framesToEndpoint))
-            framesToProcess = min(frames, boundaryFrame + 1)
+            # ceil gives the number of frames that stay strictly within the endpoint
+            framesToProcess = min(frames, int(np.ceil(framesToEndpoint)))
 
       ###########################################################################
       # PHASE 2: PITCH SHIFTING VIA TIME-STRETCH INTERPOLATION
@@ -856,7 +856,8 @@ class _RealtimeAudioPlayer:
                outdata[framesToProcess:, :] = 0.0
 
       # safety - fill any unfilled portion with silence
-      if framesToProcess < frames and self.isPlaying:
+      # skip when willHitBoundary is True: boundary handling already filled remainder (via recursion or explicit zero-fill)
+      if framesToProcess < frames and self.isPlaying and not willHitBoundary:
          outdata[framesToProcess:, :] = 0.0
 
       # update pan smoothing (prevents clicks from abrupt pan changes)

{creativepython-1.1.6 → creativepython-1.2/src/CreativePython.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: CreativePython
-Version: 1.1.6
+Version: 1.2
 Summary: A Python-based software environment for developing algorithmic art projects.
 Author-email: "Dr. Bill Manaris" <manaris@cofc.edu>, Taj Ballinger <ballingertj@g.cofc.edu>, Trevor Ritchie <ritchiets@g.cofc.edu>
 License: MIT License

{creativepython-1.1.6 → creativepython-1.2}/src/CreativePython.egg-info/SOURCES.txt

@@ -3,6 +3,7 @@ LICENSE-PSF
 MANIFEST.in
 README.md
 pyproject.toml
+src/animation.py
 src/gui.py
 src/iannix.py
 src/image.py
@@ -93,6 +94,8 @@ tests/testGameboard.py
 tests/testHitTesting.py
 tests/testPeer.py
 tests/testToolTips.py
+tests/test_crescendo.py
+tests/test_crescendo_import.py
 tests/test_keyEvent.py
 tests/test_midi.py
 tests/test_osc.py

{creativepython-1.1.6 → creativepython-1.2}/src/CreativePython.egg-info/top_level.txt

@@ -1,4 +1,5 @@
 CreativePython
+animation
 bin
 gui
 iannix

creativepython-1.2/src/animation.py

@@ -0,0 +1,554 @@
+#######################################################################################
+# animation.py       Version 1.0     18-Apr-2026     Bill Manaris and Taj Ballinger
+#######################################################################################
+
+
+# The animation library provides a simplified way to automate repeated calling of functions
+# for animation or other automation effects. Examples may range from continuously animating 
+# GUI graphics (similar to MIT Processing's draw() loop), to sequencing precise, data-driven 
+# musical automation (such as volume envelopes or filter sweeps). 
+#
+# It uses a single "master" timer, which makes sure that all visual, audio, and other effects
+# are perfectly synchronized (unlike creating individual timers for each). This is very important.
+#
+# It provides an Animate static class that can register functions to call repeatedly to support various scenarios. 
+# Anything more involved can be created using regular timers (via the timer library).
+#
+# Additionally, it provides a few shorthand functions, like animate(), setAnimationRate(), etc.
+#
+# NOTE:  Animation engine is initialized (i.e., master timer starts ticking) at module load time!!!
+#        This doesn't cost much, and simplifies life...
+
+class Animate:
+   """
+   Animate provides methods to automate calling of user-provided functions using a common, lock-step
+   time interval (or framerate).
+   """
+   _ENGINE     = None             # master timer, created and started at module load time
+   _interval   = 1000.0 / 60.0    # current timer interval (in ms)
+   _actionList = []               # list of registered callback functions to automate
+
+
+   @staticmethod
+   def _init():
+      """
+      Initialize and start master animation timer.
+      """
+
+      # initialize only if engine has not been created previously
+      if Animate._ENGINE is None:   # no engine available? 
+
+         # yes, so create a new engine and start it
+         from timer import Timer
+
+         # use a regular timer (i.e., our master timer) to call every interval
+         # our tick function (which in turns calls all registered functions appropriately)
+         # Timer(delay, callback, arguments, repeat)
+         Animate._ENGINE = Timer(Animate._interval, Animate._tick, [], True)   # create it
+         Animate._ENGINE.start()                                               # and start it!!!
+
+      # now, the master timer is running, ready to call any function that gets registered
+
+
+   @staticmethod
+   def _tick():
+      """
+      Call each registered callback function once.
+      """
+      # iterate through the list of registered actions
+      for action in Animate._actionList:
+
+         if callable(action):   # is this a function?
+
+            # yes, so execute it!!
+            action()
+
+      # now, all registered functions have been called one time
+
+
+   @staticmethod
+   def resume():
+      """
+      Resume the animation.
+      """
+
+      if Animate._ENGINE is not None:   # do we have an engine?
+
+         # yes, so resume it (starting it continues where we left off...)
+         Animate._ENGINE.start()
+
+
+   @staticmethod
+   def pause():
+      """
+      Pause the animation.
+      """
+
+      if Animate._ENGINE is not None:   # do we have an engine?
+
+         # yes, so pause it (stopping simply stops ticking - everything else remains in place!!)
+         Animate._ENGINE.stop()
+
+
+   @staticmethod
+   def add(action):
+      """
+      Register action (a callback function) to automate calling it.
+      A function may be registered several times (hopefully with different parameters).
+      """
+
+      if callable(action):   # is this a function?
+         
+         # yes, so add it to list of functions to be called
+         Animate._actionList.append(action)
+
+      else:
+
+         # let them know that something is wrong...
+         print(f"Animate.add(): '{action}' is not a callable function.")
+
+
+   @staticmethod
+   def addWithValues(action, values, duration=None, repeat=1, whenDone=None):
+      """
+      Register 'action' (a callback function) to be called repeatedly, passing it a sequence 
+      of 'values' over a specified 'duration'.  This will be repeated 'repeat' times.
+      When this process is finished, function 'whenDone' is called (if provided).
+      """
+
+      if not callable(action):   # is it NOT a function?
+
+         # let them know something is wrong...
+         print(f"Animate.addWithValues(): '{action}' is not a callable function.")
+
+      elif len(values) == 0:     # is the list empty?
+
+         # let them know something is wrong...
+         print("Animate.addWithValues(): 'values' list is empty.")
+
+      else:   # value list is not empty, so...
+
+         if duration is None:   # default duration?
+
+            timeDelayBetweenValues = Animate._interval   # use engine's default interval
+
+         else:   # they have provided their own time-stretching, so...
+
+            # calculate time delay (in millisecs) between values
+            timeDelayBetweenValues = (duration * 1000.0) / len(values)
+
+         # now, timeDelayBetweenValues contains how long we should wait to process next value... 
+
+         # check if this makes sense...
+         if timeDelayBetweenValues < Animate._interval:   # is duration provided too small for our frame rate?
+            
+            # calculate the minimum possible duration for the error message
+            minAllowableDuration = (Animate._interval * len(values)) / 1000.0
+            
+            # let them know something is wrong...
+            print(f"Animate.addWithValues(): duration ({duration}s) is too short to process, given frame rate ({Animate.getRate()})")
+            print(f"                         Should be at least {minAllowableDuration:.2f} secs.")
+
+         else:   # all good, so proceed...
+
+            import time
+
+            #####
+            # Now, we will build a closure (inner function) to handle processing each individual value, 
+            # as well as anything else that may need to happen (i.e., start over for the next repetition,
+            # or call the 'whenDone' function if we are completely done - after the last value).
+
+            # A closure needs some non-local (i.e., external to it) variables to remember how far it has gone.
+
+            # NOTE:  Every time addWithValues() above gets called, new variables are created here, 
+            #        and these are combined with the closure below, maintaining its state persistently
+            #        without overwriting each other - it works well.
+
+            # external variables to be wrapped within the closure
+            valuesIndex   = 0   # points to next value to be processed
+            repeatCounter = 0   # how many repetitions done so far
+
+            # timer delay (in millisecs) for each value
+            delay = timeDelayBetweenValues
+            
+            # remembers when the previous execution happened
+            previousTime = time.time() * 1000.0   # initialize to "now"...
+
+            # define an inner function (closure) that contains the logic of what to do 
+            # with each provided value... 
+            def processEachValueClosure():
+
+               nonlocal previousTime    # remembers when previous execution happened
+               nonlocal valuesIndex     # remembers which value is to be processed this time
+               nonlocal repeatCounter   # remembers how many times we have processed the complete value list
+
+               # get current time (in millisecs)
+               currentTime = time.time() * 1000.0
+               
+               # has enough time passed to trigger the next value?
+               if (currentTime - previousTime) >= delay:
+                  
+                  # yes, update time tracker
+                  previousTime = previousTime + delay
+                  
+                  # act only if there are remaining values to be processed
+                  if valuesIndex < len(values):   # any left?
+                     
+                     # yes, so...
+                     
+                     # get next value
+                     value = values[valuesIndex]
+                     
+                     # NOTE: this is the important step that advances the animation!!!
+                     action(value)   # execute the original callback with the current value 
+                     
+                     # point to next value to be processed (if any)
+                     valuesIndex = valuesIndex + 1
+
+                  # now, the current value has been processed...
+                     
+                  # have we completed processing all the values?
+                  if valuesIndex >= len(values):   # no more values left?
+                     
+                     # yes, we are done... so, advance to the next repetition (if any)
+                     repeatCounter = repeatCounter + 1
+
+                     # do we have more repetitions?
+                     if repeat == -1 or repeatCounter < repeat:   
+                        
+                        # yes, so start processing values once more
+                        valuesIndex = 0   # point to first value
+
+                     else:   # we are done repeating, so...
+
+                        # remove this inner function from the engine...
+                        Animate.remove( processEachValueClosure )
+                        
+                        # and execute the callback (if any)
+                        if callable(whenDone):   # is there a completion callback?
+                           
+                           # yes, so execute it!!
+                           whenDone()
+
+               # now, we have finished processing current value, and have taken care
+               # of anything else that may have needed to happen (i.e., start over next repetition,
+               # or called 'whenDone' function, if we are completely done - after this value) 
+
+            # NOTE:  Very important - now that this inner function has been built, 
+            #        we need to register it with our engine, so it can do its job...
+
+            # register the closure to be called - it will take care of everything else...
+            Animate._actionList.append(processEachValueClosure)
+
+
+   @staticmethod
+   def addWithTimedValues(action, values, times, duration=None, repeat=1, whenDone=None):
+      """
+      Register 'action' (a callback function) to be called repeatedly. 
+      'values' is a list of sublists containing the parameters to be passed to the action.
+      'times' is a parallel list containing the target timestamps (in millisecs) for each value.
+      This will be repeated 'repeat' times.
+      When this process is finished, function 'whenDone' is called (if provided).
+      """
+
+      if not callable(action):   # is it NOT a function?
+
+         # let them know that something is wrong...
+         print(f"Animate.addWithTimedValues(): '{action}' is not a callable function.")
+
+      elif len(values) == 0:     # is the list empty?
+
+         # let them know that something is wrong...
+         print("Animate.addWithTimedValues(): 'values' list is empty.")
+
+      elif len(values) != len(times):   # are the lists not parallel?
+
+         # let them know that something is wrong...
+         print(f"Animate.addWithTimedValues(): length of 'values' ({len(values)}) and 'times' ({len(times)}) must be the same.")
+
+      else:   # lists are non-empty and parallel, so...
+
+         # calculate all raw intervals between consecutive times
+         # (if list has only 1 item, intervals will be empty)
+         intervals = [times[i] - times[i-1] for i in range(1, len(times))]
+
+         # check for simultaneous or out-of-order timestamps
+         if len(intervals) > 0 and min(intervals) <= 0:
+
+            # let them know that something is wrong...
+            print(f"Animate.addWithTimedValues(): all timestamps should be larger than their previous one.")
+
+         else:   # timestamps are valid and strictly increasing, so check engine limits...
+
+            # initialize default time scale (no time-stretching)
+            timeScale = 1.0
+
+            if duration is not None:   # did they provide duration?
+
+               # find the original duration (very last element in the times sequence)
+               originalDuration = float(times[-1])
+
+               if originalDuration > 0:
+
+                  # calculate scale factor to stretch/compress the overall timing
+                  timeScale = (duration * 1000.0) / originalDuration
+
+            # adjust the smallest raw interval by our timeScale to see what the engine will actually process
+            isTooSmall = False
+            
+            if len(intervals) > 0:
+               
+               minInterval = min(intervals) * timeScale
+               
+               if minInterval < Animate._interval:   # is the smallest gap too tight?
+                  
+                  isTooSmall = True   # remember that
+
+            # now, either isTooSmall is True, meaning the tightest gap is invalid, or
+            # it is False, meaning all intervals are valid 
+
+            if isTooSmall:   # did we find an interval that is too small?
+               
+               # calculate what the scale factor WOULD need to be to make the smallest gap fit the engine
+               # (we can safely divide by min(intervals) here because we proved > 0 in the previous block)
+               requiredScaleFactor = Animate._interval / float(min(intervals))
+               
+               # calculate the minimum allowable duration (in seconds) based on that scale factor
+               originalDuration = float(times[-1])
+               minAllowableDuration = (requiredScaleFactor * originalDuration) / 1000.0
+               
+               if duration is not None:   # did they provide a duration?
+                  
+                  # let them know their duration is too short
+                  print(f"Animate.addWithTimedValues(): duration ({duration} secs) is too small to process, given frame rate ({Animate.getRate()}).")
+                  print(f"                              Should be at least {minAllowableDuration:.2f} secs.")
+                  
+               else:   # they didn't provide a duration, but the raw timestamps are too tight
+                  
+                  # let them know they need to stretch the sequence
+                  print(f"Animate.addWithTimedValues(): found time interval that is too small ({minInterval} secs), given frame rate ({Animate.getRate()}).")
+                  print(f"                              Increase interval between times, or provide a duration of at least {minAllowableDuration:.2f} secs.")
+            
+            else:   # all good, so proceed...
+
+               import time
+
+               #####
+               # Now, we will build a closure (inner function) to handle processing each individual value, 
+               # as well as anything else that may need to happen (i.e., start over for the next repetition,
+               # or call the 'whenDone' function if we are completely done - after the last value).
+
+               # A closure needs some non-local (i.e., external to it) variables to remember how far it has gone.
+
+               # NOTE:  Every time addWithTimedValues() above gets called, new variables are created here, 
+               #        and these are combined with the closure below, maintaining its state persistently
+               #        without overwriting each other - it works well.
+
+               # external variables to be wrapped within the closure
+               valuesIndex   = 0   # points to next value to be processed
+               repeatCounter = 0   # how many repetitions done so far
+
+               # remembers when the current animation sequence started
+               sequenceStartTime = time.time() * 1000.0   # initialize to "now"...
+
+               # define an inner function (closure) that contains the logic of what to do 
+               # with each provided value... 
+               def processEachTimedValueClosure():
+
+                  nonlocal sequenceStartTime   # remembers when the current sequence repetition started
+                  nonlocal valuesIndex         # remembers which value is to be processed this time
+                  nonlocal repeatCounter       # remembers how many times we have processed the complete value list
+
+                  # get current time (in millisecs)
+                  currentTime = time.time() * 1000.0
+                  
+                  # calculate how much time has elapsed since the sequence started
+                  elapsedTime = currentTime - sequenceStartTime
+                  
+                  # get the target timestamp directly from the times list (adjusted by our timeScale)
+                  targetTimestamp = times[valuesIndex] * timeScale
+
+                  # has enough time passed to trigger the next value based on its target timestamp?
+                  if elapsedTime >= targetTimestamp:
+                     
+                     # yes, so...
+                     
+                     # get the arguments directly from the values list
+                     actionArgs = values[valuesIndex]
+                     
+                     # NOTE: this is the important step that advances the animation!!!
+                     # unpack the arguments (*) and execute the original callback
+                     action(*actionArgs)   
+                     
+                     # point to next value to be processed (if any)
+                     valuesIndex = valuesIndex + 1
+
+                     # now, the current value has been processed...
+                        
+                     # have we completed processing all the values?
+                     if valuesIndex >= len(values):   # no more values left?
+                        
+                        # yes, we are done... so, advance to the next repetition (if any)
+                        repeatCounter = repeatCounter + 1
+
+                        # do we have more repetitions?
+                        if repeat == -1 or repeatCounter < repeat:   
+                           
+                           # yes, so start processing values once more
+                           valuesIndex = 0   # point to first value
+                           
+                           # reset the sequence start time for the next repetition cycle
+                           sequenceStartTime = time.time() * 1000.0
+
+                        else:   # we are done repeating, so...
+
+                           # remove this inner function from the engine...
+                           Animate.remove( processEachTimedValueClosure )
+                           
+                           # and execute the callback (if any)
+                           if callable(whenDone):   # is there a completion callback?
+                              
+                              # yes, so execute it!!
+                              whenDone()
+
+                  # now, we have finished processing current value, and have taken care
+                  # of anything else that may have needed to happen (i.e., start over next repetition,
+                  # or called 'whenDone' function, if we are completely done - after this value) 
+
+               # NOTE:  Very important - now that this inner function has been built, 
+               #        we need to register it with our engine, so it can do its job...
+
+               # register the closure to be called - it will take care of everything else...
+               Animate._actionList.append(processEachTimedValueClosure)
+
+
+   @staticmethod
+   def remove(action):
+      """
+      Remove a callback function from the list of functions being called.
+      If a function is registered several times, it removes the earliest addition.
+      """
+      
+      if action in Animate._actionList:   # is this a previously registered function?
+
+         # yes, so remove first matching occurrence
+         Animate._actionList.remove(action)
+
+      else:
+
+         # let them know that something is wrong...
+         print(f"Animate.remove(): '{action}' does not appear in the list of registered functions.")
+
+
+   @staticmethod
+   def getRate():
+      """
+      Return current animation rate (in frames per second).
+      """
+ 
+      # convert milliseconds back to frames per second
+      return int(1000.0 / Animate._interval)
+
+
+   @staticmethod
+   def setRate(frameRate=60):
+      """
+      Set current animation rate (in frames per second).
+      """
+
+      # convert frames per second to milliseconds
+      Animate._interval = (1000.0 / frameRate)
+      
+      if Animate._ENGINE is not None:   # do we have an engine?
+
+         # yes, so update the engine
+         Animate._ENGINE.setDelay(Animate._interval)
+
+
+#####
+# NOTE:  This is important - initialize engine and start master timer at module load time.
+#        Leave it here!!!
+Animate._init()
+
+
+####
+# function aliases for backwards compatibility / simplicity
+def animate(action):
+   """
+   Add a function to be called repeatedly by animation engine.
+   """
+
+   Animate.add(action)
+
+
+def setAnimationRate(frameRate=60):
+   """
+   Set animation frame rate (frames per second).
+   """
+
+   Animate.setRate(frameRate)
+
+   
+def getAnimationRate():
+   """
+   Return current animation frame rate (frames per second).
+   """
+
+   return Animate.getRate()
+
+
+def pauseAnimation():
+   """
+   Pause animation (everything else remains in place).
+   """
+   Animate.pause()
+
+
+def resumeAnimation():
+   """
+   Resume stopped animation (everything continues from where it had left off).
+   """
+
+   Animate.resume()
+
+
+####
+# Helper functions
+
+from music import mapValue   # import mapValue from music library
+
+def mapValueList(values, minValue, maxValue, minResult, maxResult):
+   """
+   Map a sequence of 'values' from their original range (defined by 'minValue' 
+   and 'maxValue') to a new range defined by 'minResult' and 'maxResult'.
+   Returns a new list containing the mapped values.
+   """
+
+   newValues = []   # holds mapped values
+
+   # do some sanity checking...
+   if type(values) is not list:   # are the provided values NOT in a list?
+
+      # let them know something is wrong...
+      print(f"mapValueList(): '{values}' is not a valid list.")
+
+   elif len(values) == 0:   # is the list empty?
+
+      # let them know something is wrong...
+      print("mapValueList(): 'trajectoryValues' list is empty.")
+
+   else:   # all good, so proceed...
+
+      # map each value in provided list
+      for value in values:
+
+         # map this value from source to target range
+         newValue = mapValue(value, minValue, maxValue, minResult, maxResult)
+
+         # and remember it...
+         newValues.append(newValue)
+
+      # now, newValues contains scaled values...
+
+   # and return it (empty, if validation checks fail)
+   return newValues