CreativePython 1.0.0__tar.gz → 1.1.0__tar.gz

{creativepython-1.0.0/src/CreativePython.egg-info → creativepython-1.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: CreativePython
-Version: 1.0.0
+Version: 1.1.0
 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
@@ -53,6 +53,7 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 License-File: LICENSE-PSF
 Requires-Dist: setuptools>=69.0
+Requires-Dist: wheel>=0.46.0
 Requires-Dist: tinysoundfont>=0.3.6
 Requires-Dist: osc4py3>=1.0.8
 Requires-Dist: mido>=1.3.3

{creativepython-1.0.0 → creativepython-1.1.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "CreativePython"
-version = "1.0.0"
+version = "1.1.0"
 description = "A Python-based software environment for developing algorithmic art projects."
 readme = "README.md"
 license = { file = "LICENSE" }
@@ -22,6 +22,7 @@ classifiers = [
 ]
 dependencies = [
    "setuptools>=69.0",
+   "wheel>=0.46.0",
    "tinysoundfont>=0.3.6",
    "osc4py3>=1.0.8",
    "mido>=1.3.3",

creativepython-1.1.0/src/CreativePython/GuiHandler.py

@@ -0,0 +1,518 @@
+#######################################################################################
+# GuiHandler.py    Version 1.0    12-Mar-2026
+# Taj Ballinger, Bill Manaris
+#######################################################################################
+#
+# GuiHandler runs in the main CreativePython process.
+# It manages the GuiRenderer child process, delivers commands to Qt, and
+# receives responses and events in return.
+#
+# This file contains no Qt code and never imports PySide6.
+# All Qt activity lives in GuiRenderer.py, which runs in the child process.
+#
+# See GuiRenderer.py for the full protocol description.
+#
+
+import multiprocessing
+import threading
+import atexit
+
+
+#######################################################################################
+# Message Protocol Helpers
+#
+# Plain-dict message constructors shared by GuiHandler (parent) and GuiRenderer (child).
+# Keeping them here avoids any import of Qt in the parent process — GuiRenderer imports
+# these helpers from this file, not the other way around.
+#######################################################################################
+
+def _createCommand(action, target, args=None, responseId=None):
+   """
+   Creates a command message dict (CreativePython -> Qt).
+   """
+   return {
+      'action':     action,
+      'target':     target,
+      'args':       args if args is not None else {},
+      'responseId': responseId
+   }
+
+def _createResponse(responseId, values=None):
+   """
+   Creates a response message dict (Qt -> CreativePython).
+   """
+   return {
+      'responseId': responseId,
+      'values':     values if values is not None else []
+   }
+
+def _createEvent(eventType, target, args=None):
+   """
+   Creates an event message dict (Qt -> CreativePython).
+   """
+   return {
+      'type':   eventType,
+      'target': target,
+      'args':   args if args is not None else {}
+   }
+
+
+#######################################################################################
+# Child process entry point
+#######################################################################################
+
+def _launchRenderer(childConn):
+   """
+   Entry point for the GuiRenderer child process.
+   Defined here so GuiHandler can reference it without importing from GuiRenderer
+   globally (which would also import Qt/PySide6 in the parent process).
+
+   At runtime this function only executes in the child process.
+   """
+   import sys, os
+
+   # Suppress macOS system noise (stale XPC connections inherited via fork)
+   # that would confuse students.  Redirect at the OS level (fd 2) so that
+   # C-level libraries (Cocoa, XPC) are also silenced.
+   _devnull = os.open(os.devnull, os.O_WRONLY)
+   os.dup2(_devnull, 2)
+   os.close(_devnull)
+   sys.stderr = open(os.devnull, 'w')
+
+   from CreativePython.GuiRenderer import GuiRenderer
+   renderer = GuiRenderer(childConn)
+   renderer.run()
+
+
+#######################################################################################
+# GuiHandler
+#######################################################################################
+
+class GuiHandler:
+   """
+   Runs in the main CreativePython process.
+   Manages the GuiRenderer child process, sends commands, and receives
+   responses and events.  Instantiated once as the module-level singleton
+   _GUI_HANDLER when gui.py is imported; never exposed directly to the user.
+   """
+
+   def __init__(self):
+      """
+      Spawns the GuiRenderer child process and establishes the IPC Pipe.
+      Starts a background listener thread that routes incoming messages to
+      waiting sendQuery() callers or registered event callbacks.
+      Registers an atexit handler so the child is always cleaned up when
+      the parent process exits — no cleanup code required in gui.py.
+      """
+      parentConn, childConn = multiprocessing.Pipe(duplex=True)
+      self.connection = parentConn
+
+      # Choose the spawn context based on the runtime environment:
+      #
+      #   fork       — fastest; child inherits parent memory without re-importing
+      #                anything.  Safe when the parent has no Cocoa/AppKit state.
+      #
+      #   forkserver — the forkserver helper is started once via 'spawn' (clean,
+      #                no inherited GUI state); each child is then forked from
+      #                that clean server.  Required under PENCIL: PENCIL's
+      #                user-subprocess imports tkinter (Cocoa/AppKit), and forking
+      #                directly from that process prevents Qt from connecting to
+      #                the macOS window server.
+      #
+      #   spawn      — every child is a fresh Python process; re-imports __main__,
+      #                which would re-run the user's script.  Used on Windows where
+      #                fork is unavailable.
+      #
+      # Detection: if tkinter has been imported into the current process, Cocoa is
+      # live and we must avoid fork.  Otherwise, fork is safe and avoids the
+      # __main__ re-import problem that spawn/forkserver have.
+      import sys
+      if sys.platform == 'win32':
+         ctx = multiprocessing.get_context('spawn')
+      elif getattr(sys, 'frozen', False):
+         # Running inside a PyInstaller frozen executable.  forkserver spawns
+         # its helper by calling sys.executable as a Python interpreter, which
+         # doesn't work when sys.executable is the frozen app binary.  spawn
+         # is safe here because freeze_support() in the entry point intercepts
+         # the --multiprocessing-fork flag before any app code runs.
+         ctx = multiprocessing.get_context('spawn')
+      elif 'tkinter' in sys.modules:
+         ctx = multiprocessing.get_context('forkserver')
+      else:
+         ctx = multiprocessing.get_context('fork')
+      # With 'spawn' on POSIX (fork+exec), the forked helper calls
+      # get_preparation_data() which reads sys.modules['__main__'].__file__.
+      # When a user script is running in PENCIL's subprocess, __main__.__file__
+      # is set to that script's path (IDLE does this before exec'ing the script).
+      # That path ends up in the bootstrap pipe; the GuiRenderer child's prepare()
+      # then re-imports the user's script before _launchRenderer ever runs.
+      # If the script raises at module level (no __main__ guard, missing imports,
+      # etc.) GuiRenderer crashes silently and the pipe breaks.
+      # Fix: clear __main__.__file__ and __spec__ for the duration of the fork so
+      # get_preparation_data() omits main_path and prepare() skips the re-import.
+      _main_mod   = sys.modules.get('__main__')
+      _saved_file = getattr(_main_mod, '__file__', _UNSET := object())
+      _saved_spec = getattr(_main_mod, '__spec__', _UNSET)
+      if _main_mod is not None:
+         _main_mod.__file__ = None
+         _main_mod.__spec__ = None
+      try:
+         self.childProcess = ctx.Process(
+            target = _launchRenderer,
+            args   = (childConn,),
+            daemon = True   # child is killed automatically if parent dies unexpectedly
+         )
+         self.childProcess.start()
+      finally:
+         if _main_mod is not None:
+            if _saved_file is not _UNSET:
+               _main_mod.__file__ = _saved_file
+            if _saved_spec is not _UNSET:
+               _main_mod.__spec__ = _saved_spec
+      childConn.close()   # parent no longer needs the child end of the Pipe
+
+      # responseId counter — each sendQuery() call gets a unique ID so the
+      # listener thread can route the response back to the correct caller
+      self._responseIdCount = 0
+      self._responseIdLock  = threading.Lock()
+
+      # pending responses — maps responseId -> {'event': threading.Event, 'values': list}
+      # sendQuery() registers a slot here before sending, then blocks on the Event.
+      # The listener thread writes values into the slot and signals the Event.
+      self._pendingResponses = {}
+      self._pendingLock      = threading.Lock()
+
+      # event registry — maps (objectId, eventType) -> callback function
+      # Populated by registerEvent(); consulted by the listener thread on each event.
+      self._eventRegistry = {}
+
+      # send lock — Pipe.send() is not thread-safe; all outgoing messages
+      # must acquire this lock before writing to the pipe
+      self._sendLock = threading.Lock()
+
+      # single listener thread handles both responses and events, since both
+      # arrive on the same connection and reading from it on two threads would race
+      self._listenerThread = threading.Thread(
+         target = self._listenForMessages,
+         daemon = True   # thread exits automatically when the main process exits
+      )
+      self._listenerThread.start()
+
+      atexit.register(self._shutdown)
+
+   # ── Response ID ───────────────────────────────────────────────────────────
+
+   def _nextResponseId(self):
+      """
+      Returns the next unique responseId.  Thread-safe.
+      """
+      with self._responseIdLock:
+         self._responseIdCount += 1
+         return self._responseIdCount
+
+   # ── Listener thread ───────────────────────────────────────────────────────
+
+   def _listenForMessages(self):
+      """
+      Background thread.  Reads all incoming messages from GuiRenderer and
+      routes each one based on its type:
+        - 'responseId' key present → response for a waiting sendQuery() call
+        - 'type' key present       → event for a registered callback
+      Exits when the pipe is closed (EOFError).
+      """
+      while True:
+         try:
+            message = self.connection.recv()
+            if 'responseId' in message:
+               self._handleResponse(message)
+            elif 'type' in message:
+               self._dispatchEvent(message)
+         except EOFError:
+            break   # pipe closed; thread exits cleanly
+
+   def _handleResponse(self, responseDict):
+      """
+      Routes an incoming response to the sendQuery() call that is waiting for it.
+      Called from the listener thread.
+      """
+      responseId = responseDict.get('responseId')
+      values     = responseDict.get('values', [])
+
+      with self._pendingLock:
+         pendingSlot = self._pendingResponses.get(responseId)
+
+      if pendingSlot is not None:
+         pendingSlot['values'] = values   # store result before signalling
+         pendingSlot['event'].set()       # unblock the waiting sendQuery() call
+
+   # ── Sending ───────────────────────────────────────────────────────────────
+
+   def sendCommand(self, action, target, args=None):
+      """
+      Sends a fire-and-forget command to GuiRenderer (no response expected).
+      Thread-safe.
+      """
+      command = _createCommand(action, target, args)
+      with self._sendLock:
+         self.connection.send(command)
+
+   def sendQuery(self, action, target, args=None):
+      """
+      Sends a command to GuiRenderer and blocks until a response is received.
+      Returns the response's values list.  Thread-safe; multiple callers may
+      block concurrently — each is matched to its response by responseId.
+      """
+      responseId  = self._nextResponseId()
+      pendingSlot = {'event': threading.Event(), 'values': None}
+
+      # register the slot before sending so the listener never misses the response
+      with self._pendingLock:
+         self._pendingResponses[responseId] = pendingSlot
+
+      command = _createCommand(action, target, args, responseId=responseId)
+      with self._sendLock:
+         self.connection.send(command)
+
+      pendingSlot['event'].wait()   # block until the listener signals a response
+
+      with self._pendingLock:
+         del self._pendingResponses[responseId]   # clean up the slot
+
+      return pendingSlot['values']
+
+   # ── Developer utilities ───────────────────────────────────────────────────
+
+   def getBatchSize(self):
+      """
+      Returns the current _BATCH_SIZE used by GuiRenderer's pipe-polling loop.
+      Not part of the public API — intended for developer tuning only.
+      """
+      result = self.sendQuery('getBatchSize', None)
+      return result[0]
+
+   def setBatchSize(self, batchSize):
+      """
+      Sets GuiRenderer's _BATCH_SIZE on the fly.
+      Higher values process more commands between Qt repaints (better throughput,
+      less responsive feel); lower values yield more frequent repaints.
+      Not part of the public API — intended for developer tuning only.
+      """
+      self.sendCommand('setBatchSize', None, {'batchSize': batchSize})
+
+   # ── Events ────────────────────────────────────────────────────────────────
+
+   def registerEvent(self, objectId, eventType, callback):
+      """
+      Registers a callback for a specific event type on a specific object.
+      Stores the callback locally and notifies GuiRenderer to watch for the
+      corresponding Qt event on that object.
+      When GuiRenderer sends a matching event, the callback is invoked with
+      the event's args dict unpacked as keyword arguments.
+      """
+      self._eventRegistry[(objectId, eventType)] = callback
+
+      registrationArgs = {'objectId': objectId, 'eventType': eventType}
+      self.sendCommand('registerEvent', None, registrationArgs)
+
+   def _dispatchEvent(self, eventDict):
+      """
+      Looks up and calls the callback registered for the incoming event.
+      Called from the listener thread; the callback runs on that thread.
+      """
+      eventType = eventDict.get('type')
+      objectId  = eventDict.get('target')
+      args      = eventDict.get('args', {})
+
+      callback = self._eventRegistry.get((objectId, eventType))
+      if callback is not None and callable(callback):
+         if isinstance(args, list):
+            callback(*args)
+         else:
+            callback(**args)
+
+   # ── Shutdown ──────────────────────────────────────────────────────────────
+
+   def _shutdown(self):
+      """
+      Kills the child process immediately and closes the pipe.
+      Called automatically via atexit when the parent process exits.
+      The child is killed with SIGKILL so it does not drain its event queue —
+      exit() in the parent should return promptly.
+      """
+      if self.childProcess.is_alive():
+         # SIGTERM is overridden in the child to call os._exit(0) immediately,
+         # bypassing Qt's graceful shutdown (which drains the event queue).
+         # Python delivers SIGTERM between bytecodes, so it fires within one
+         # iteration of the child's _pollPipe loop — far faster than SIGKILL,
+         # which macOS may defer while a Metal/GPU operation is in flight.
+         self.childProcess.terminate()
+         self.childProcess.join(timeout=0.5)   # should die in < 1 ms
+      if self.childProcess.is_alive():
+         self.childProcess.kill()              # backup: SIGKILL
+         self.childProcess.join(timeout=2.0)
+      self.connection.close()
+
+
+#######################################################################################
+# Handler factory
+#######################################################################################
+
+class _NullHandler:
+   """
+   Stub returned by _createHandler() when called from a spawned child process.
+
+   On Windows (and forkserver on macOS), multiprocessing re-imports __main__
+   to reconstruct the child's environment.  Any top-level Display or shape
+   creation in the user's script would run again during that re-import.
+   Returning this stub makes all those calls silently do nothing instead of
+   crashing with a RuntimeError or starting another child process.
+   """
+   def sendCommand(self, action, target, args=None): pass
+   def sendQuery(self,   action, target, args=None): return [0, 0, 0, 0]
+   def registerEvent(self, objectId, eventType, callback): pass
+   def getBatchSize(self): return 0
+   def setBatchSize(self, batchSize): pass
+
+
+def _createHandler():
+   """
+   Returns a GuiHandler if called from the main process, or a _NullHandler
+   if called from a spawned/forked child process (e.g. during __main__ re-import).
+   Also calls freeze_support() and waits briefly for the child process to start.
+   """
+   if multiprocessing.parent_process() is not None:
+      return _NullHandler()
+   multiprocessing.freeze_support()
+   import time
+   handler = GuiHandler()
+   time.sleep(0.2)   # allow child process to start
+   return handler
+
+
+#######################################################################################
+# Phase 4 Test
+#######################################################################################
+
+if __name__ == '__main__':
+   # On macOS/Windows, multiprocessing uses 'spawn' by default.
+   # This guard prevents the child process from re-running the test on import.
+   multiprocessing.freeze_support()
+
+   import time
+
+   PASS = '\033[92m✓\033[0m'
+   FAIL = '\033[91m✗\033[0m'
+
+   def check(label, condition):
+      print(f'  {PASS if condition else FAIL}  {label}')
+      if not condition:
+         raise AssertionError(f'FAILED: {label}')
+
+   print()
+   print('GuiHandler / GuiRenderer — Phase 4 Test')
+   print('=' * 40)
+   print('  (A small window will appear briefly during this test.)')
+
+   handler = GuiHandler()
+   time.sleep(0.2)   # allow Qt event loop to start
+
+   DISPLAY_ID = 1   # objectId used for the test Display
+
+   # ── Create Display ────────────────────────────────────────────────────────
+   print('\n[1] Create Display')
+
+   createArgs = {
+      'type':   'Display',
+      'title':  'Phase 4 Test',
+      'width':  300,
+      'height': 200,
+      'x':      100,
+      'y':      100,
+      'color':  [255, 255, 255, 255]   # white
+   }
+   handler.sendCommand('create', DISPLAY_ID, createArgs)
+   time.sleep(0.2)   # allow Qt to create and show the window
+
+   pingResult = handler.sendQuery('ping', None)
+   check('Qt event loop alive after create', pingResult == ['pong'])
+
+   # ── Query initial state ───────────────────────────────────────────────────
+   print('\n[2] Query initial state')
+
+   titleResult = handler.sendQuery('getTitle', DISPLAY_ID)
+   check('getTitle returns "Phase 4 Test"', titleResult == ['Phase 4 Test'])
+
+   sizeResult = handler.sendQuery('getSize', DISPLAY_ID)
+   check('getSize returns [300, 200]', sizeResult == [300, 200])
+
+   widthResult = handler.sendQuery('getWidth', DISPLAY_ID)
+   check('getWidth returns 300', widthResult == [300])
+
+   heightResult = handler.sendQuery('getHeight', DISPLAY_ID)
+   check('getHeight returns 200', heightResult == [200])
+
+   colorResult = handler.sendQuery('getColor', DISPLAY_ID)
+   check('getColor returns [255, 255, 255, 255]', colorResult == [255, 255, 255, 255])
+
+   posResult = handler.sendQuery('getPosition', DISPLAY_ID)
+   check('getPosition returns two integers',
+         len(posResult) == 2 and all(isinstance(v, int) for v in posResult))
+
+   # ── Setters round-trip ────────────────────────────────────────────────────
+   print('\n[3] Setters round-trip')
+
+   handler.sendCommand('setTitle', DISPLAY_ID, {'title': 'Updated Title'})
+   titleResult2 = handler.sendQuery('getTitle', DISPLAY_ID)
+   check('setTitle → getTitle round-trips', titleResult2 == ['Updated Title'])
+
+   handler.sendCommand('setColor', DISPLAY_ID, {'color': [0, 0, 255, 255]})
+   colorResult2 = handler.sendQuery('getColor', DISPLAY_ID)
+   check('setColor → getColor round-trips', colorResult2 == [0, 0, 255, 255])
+
+   handler.sendCommand('setSize', DISPLAY_ID, {'width': 400, 'height': 300})
+   sizeResult2 = handler.sendQuery('getSize', DISPLAY_ID)
+   check('setSize → getSize round-trips', sizeResult2 == [400, 300])
+
+   handler.sendCommand('setPosition', DISPLAY_ID, {'x': 150, 'y': 150})
+   posResult2 = handler.sendQuery('getPosition', DISPLAY_ID)
+   check('setPosition returns two integers',
+         len(posResult2) == 2 and all(isinstance(v, int) for v in posResult2))
+
+   # ── Visibility ────────────────────────────────────────────────────────────
+   print('\n[4] Visibility')
+
+   handler.sendCommand('hide', DISPLAY_ID)
+   time.sleep(0.1)
+   check('Qt alive after hide', handler.sendQuery('ping', None) == ['pong'])
+
+   handler.sendCommand('show', DISPLAY_ID)
+   time.sleep(0.1)
+   check('Qt alive after show', handler.sendQuery('ping', None) == ['pong'])
+
+   time.sleep(5)  # hang for a few seconds to show Display
+
+   # ── displayClose event ────────────────────────────────────────────────────
+   print('\n[5] displayClose event')
+
+   closeReceived = []
+
+   def onDisplayClose():
+      closeReceived.append(True)
+
+   handler.registerEvent(DISPLAY_ID, 'displayClose', onDisplayClose)
+   time.sleep(0.1)
+
+   handler.sendCommand('close', DISPLAY_ID)
+   time.sleep(0.2)
+
+   check('displayClose event received', len(closeReceived) == 1)
+
+   # ── Shutdown ──────────────────────────────────────────────────────────────
+   print('\n[6] Shutdown')
+
+   handler._shutdown()
+   check('child process has exited', not handler.childProcess.is_alive())
+
+   print()
+   print('All Phase 4 tests passed.')
+   print()