release 0.10.4a2

Author: hx2A

README.md

@@ -52,8 +52,8 @@ There are currently five basic ways to use py5. They are:
 
 * **module mode**: create a sketch with `setup()` and `draw()` functions that call methods provided by the `py5` library. The above example is created in module mode.
 * **class mode**: create a Python class inherited from `py5.Sketch`. This mode supports multiple Sketches running at the same time.
-* **imported mode**: simplified code that omits the `py5.` prefix. This mode is supported by the py5 Jupyter notebook kernel and the `run_sketch` command line utility.
-* **static mode**: functionless code to create static images. This mode is supported by the py5bot Jupyter notebook kernel, the `%%py5bot` IPython magic, and the `run_sketch` command line utility.
+* **imported mode**: simplified code that omits the `py5.` prefix. This mode is supported by the py5 Jupyter notebook kernel and the `py5-run-sketch` command line utility.
+* **static mode**: functionless code to create static images. This mode is supported by the py5bot Jupyter notebook kernel, the `%%py5bot` IPython magic, and the `py5-run-sketch` command line utility.
 * **processing mode**: make calls to Python from a Processing (Java) Sketch. This mode enables py5 to function as bridge, connecting the Python and Java ecosystems through a new `callPython()` method.
 
 ## Source Code

py5/__init__.py

@@ -25,6 +25,7 @@
 
 import inspect
 import os
+import platform
 import sys
 import warnings
 from io import BytesIO
@@ -35,16 +36,64 @@
 import numpy as np  # noqa
 import numpy.typing as npt  # noqa
 import py5_tools
+import py5_tools.environ  # noqa
 from jpype import JClass  # noqa
 from jpype.types import JArray, JChar, JFloat, JInt, JString  # noqa
 from PIL import Image  # noqa
 
+_environ = py5_tools.environ.Environment()
+
 if not py5_tools.is_jvm_running():
     base_path = (
         Path(getattr(sys, "_MEIPASS")) / "py5"
         if hasattr(sys, "_MEIPASS")
         else Path(__file__).absolute().parent
     )
+
+    if platform.system() == "Darwin":
+        # Make sure Python appears on the MacOS Dock
+        # This is necessary, otherwise MacOS will not like to let JAVA2D Sketches get focus
+        try:
+            from AppKit import (
+                NSURL,
+                NSApplication,
+                NSApplicationActivationPolicyRegular,
+                NSImage,
+            )
+
+            # this adds a white square to the dock
+            app = NSApplication.sharedApplication()
+            app.setActivationPolicy_(NSApplicationActivationPolicyRegular)
+
+            # set the dock icon to the py5 logo
+            icon_path = base_path.parent / "py5_tools/resources/logo.icns"
+            icon_url = NSURL.fileURLWithPath_(str(icon_path))
+            icon_image = NSImage.alloc().initWithContentsOfURL_(icon_url)
+            app.setApplicationIconImage_(icon_image)
+
+            # cleanup
+            del app, icon_path, icon_url, icon_image
+            del NSURL, NSApplication, NSApplicationActivationPolicyRegular, NSImage
+        except:
+            pass
+
+    if platform.system() == "Windows":
+        # This code is here so that later win32gui code works correctly. The
+        # `focus_window(handle)` method in `Py5Bridge` is used to move Sketch
+        # windows to the foreground
+        try:
+            from win32com import client as win32com_client
+
+            shell = win32com_client.Dispatch("WScript.Shell")
+
+            # send the most benign key possible. this can't possibly do anything
+            shell.SendKeys(chr(0))
+
+            # cleanup
+            del win32com_client, shell
+        except:
+            pass
+
     # add py5 jars to the classpath first
     py5_tools.add_jars(str(base_path / "jars"))
     # if the cwd has a jars subdirectory, add that next
@@ -114,7 +163,7 @@
     pass
 
 
-__version__ = "0.10.3a1"
+__version__ = "0.10.4a2"
 
 _PY5_USE_IMPORTED_MODE = py5_tools.get_imported_mode()
 py5_tools._lock_imported_mode()
@@ -8019,6 +8068,32 @@ def image_mode(mode: int, /) -> None:
     return _py5sketch.image_mode(mode)
 
 
+def intercept_escape() -> None:
+    """Prevent the Escape key from causing the Sketch to exit.
+
+    Notes
+    -----
+
+    Prevent the Escape key from causing the Sketch to exit. Normally hitting the
+    Escape key (`ESC`) will cause the Sketch to exit. In Processing, one can write
+    code to change the Escape key's behavior by changing the `key` value to
+    something else, perhaps with code similar to `py5.key = 'x'`. That code won't
+    work in py5 because py5 does not allow the user to alter the value of `key` like
+    Processing does. The `intercept_escape()` method was created to allow users to
+    achieve the same goal of preventing the Escape key from causing the Sketch to
+    exit.
+
+    The `intercept_escape()` method will only do something when `key` already equals
+    `ESC`. This function should only be called from the user event functions
+    `key_pressed()`, `key_typed()`, and `key_released()`.
+
+    This method will not alter the value of `key`. This method cannot prevent a
+    Sketch from exiting when the exit is triggered by any other means, such as a
+    call to `exit_sketch()` or the user closes the window.
+    """
+    return _py5sketch.intercept_escape()
+
+
 @overload
 def lerp_color(c1: int, c2: int, amt: float, /) -> int:
     """Calculates a color between two colors at a specific increment.
@@ -23104,3 +23179,11 @@ def _prepare_dynamic_variables(caller_locals, caller_globals):
 
 
 _prepare_dynamic_variables(locals(), globals())
+
+
+if platform.system() == "Darwin" and _environ.in_ipython_session:
+    if _environ.ipython_shell.active_eventloop != "osx":
+        print(
+            "Importing py5 on macOS but the necessary Jupyter macOS event loop has not been activated. I'll activate it for you, but next time, execute `%gui osx` before importing this library."
+        )
+        _environ.ipython_shell.run_line_magic("gui", "osx")

py5/bridge.py

@@ -18,6 +18,7 @@
 #
 # *****************************************************************************
 import inspect
+import platform
 import re
 import sys
 import traceback
@@ -367,6 +368,26 @@ def call_function(self, key, params):
     def py5_println(self, text, stderr):
         self._sketch.println(text, stderr=stderr)
 
+    @JOverride
+    def focus_window(self, handle):
+        try:
+            if platform.system() == "Windows":
+                import win32gui
+
+                # win32gui.ShowWindow(hwnd, 5)
+                win32gui.SetForegroundWindow(handle)
+
+            elif platform.system() == "Darwin":
+                # not yet implemented
+                pass
+
+            elif platform.system() == "Linux":
+                # not yet implemented
+                pass
+
+        except:
+            pass
+
     @JOverride
     def shutdown(self):
         try:

py5/graphics.py

@@ -1783,15 +1783,15 @@ def color(self, *args) -> int:
     WHITESPACE = " \t\n\r\f\u00a0"
 
     def _get_height(self) -> int:
-        """System variable that stores the height of the Py5Graphics drawing surface.
+        """Variable that stores the height of the Py5Graphics drawing surface.
 
         Underlying Processing field: PGraphics.height
 
         Notes
         -----
 
-        System variable that stores the height of the Py5Graphics drawing surface. This
-        value is set when creating the `Py5Graphics` object with the `create_graphics()`
+        Variable that stores the height of the Py5Graphics drawing surface. This value
+        is set when creating the `Py5Graphics` object with the `create_graphics()`
         method. For example, `create_graphics(320, 240)` sets the `height` variable to
         the value 240.
 
@@ -1802,15 +1802,15 @@ def _get_height(self) -> int:
 
     height: int = property(
         fget=_get_height,
-        doc="""System variable that stores the height of the Py5Graphics drawing surface.
+        doc="""Variable that stores the height of the Py5Graphics drawing surface.
 
         Underlying Processing field: PGraphics.height
 
         Notes
         -----
 
-        System variable that stores the height of the Py5Graphics drawing surface. This
-        value is set when creating the `Py5Graphics` object with the `create_graphics()`
+        Variable that stores the height of the Py5Graphics drawing surface. This value
+        is set when creating the `Py5Graphics` object with the `create_graphics()`
         method. For example, `create_graphics(320, 240)` sets the `height` variable to
         the value 240.
 
@@ -1963,17 +1963,17 @@ def _get_pixel_width(self) -> int:
     )
 
     def _get_width(self) -> int:
-        """System variable that stores the width of the Py5Graphics drawing surface.
+        """Variable that stores the width of the Py5Graphics drawing surface.
 
         Underlying Processing field: PGraphics.width
 
         Notes
         -----
 
-        System variable that stores the width of the Py5Graphics drawing surface. This
-        value is set when creating the `Py5Graphics` object with the `create_graphics()`
-        method. For example, `create_graphics(320, 240)` sets the `width` variable to
-        the value 320.
+        Variable that stores the width of the Py5Graphics drawing surface. This value is
+        set when creating the `Py5Graphics` object with the `create_graphics()` method.
+        For example, `create_graphics(320, 240)` sets the `width` variable to the value
+        320.
 
         This field is the same as `width` but linked to a `Py5Graphics` object. To see
         example code for how it can be used, see `width`.
@@ -1982,17 +1982,17 @@ def _get_width(self) -> int:
 
     width: int = property(
         fget=_get_width,
-        doc="""System variable that stores the width of the Py5Graphics drawing surface.
+        doc="""Variable that stores the width of the Py5Graphics drawing surface.
 
         Underlying Processing field: PGraphics.width
 
         Notes
         -----
 
-        System variable that stores the width of the Py5Graphics drawing surface. This
-        value is set when creating the `Py5Graphics` object with the `create_graphics()`
-        method. For example, `create_graphics(320, 240)` sets the `width` variable to
-        the value 320.
+        Variable that stores the width of the Py5Graphics drawing surface. This value is
+        set when creating the `Py5Graphics` object with the `create_graphics()` method.
+        For example, `create_graphics(320, 240)` sets the `width` variable to the value
+        320.
 
         This field is the same as `width` but linked to a `Py5Graphics` object. To see
         example code for how it can be used, see `width`.""",

py5/jars/py5.jar

@@ -0,0 +1,122 @@
+# *****************************************************************************
+#
+#   Part of the py5 library
+#   Copyright (C) 2020-2024 Jim Schmitz
+#
+#   This library is free software: you can redistribute it and/or modify it
+#   under the terms of the GNU Lesser General Public License as published by
+#   the Free Software Foundation, either version 2.1 of the License, or (at
+#   your option) any later version.
+#
+#   This library is distributed in the hope that it will be useful, but
+#   WITHOUT ANY WARRANTY; without even the implied warranty of
+#   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser
+#   General Public License for more details.
+#
+#   You should have received a copy of the GNU Lesser General Public License
+#   along with this library. If not, see <https://www.gnu.org/licenses/>.
+#
+# *****************************************************************************
+import functools
+import platform
+
+from py5_tools.environ import Environment
+
+_environ = Environment()
+
+_enforce_safety_check = (
+    platform.system() == "Darwin"
+    and (
+        platform.processor() == "i386"
+        or int(platform.mac_ver()[0].split(".", 1)[0]) < 14
+    )
+    and _environ.in_ipython_session
+)
+_first_renderer_opengl = None
+
+
+def disable_safety_check():
+    global _enforce_safety_check
+    _enforce_safety_check = False
+
+
+def enable_safety_check():
+    global _enforce_safety_check
+    _enforce_safety_check = True
+
+
+OPENGL_RENDERERS = [
+    "processing.opengl.PGraphics2D",
+    "processing.opengl.PGraphics3D",
+]
+
+MESSAGE = """Sorry, but you can't use an OpenGL renderer in your Sketch right now. Doing so might cause Python to crash.
+
+Here's the problem: On macOS machines with Intel CPUs and/or older macOS versions, this version of py5 seems to crash when you use an OpenGL renderer in an IPython or Jupyter session if the first Sketch run in that Python session used the default (JAVA2D) renderer. Sorry if that sounds crazy. This is an unfortunate side effect of an important code change that significantly improved py5 for all macOS users.
+
+The root issue is somewhere in native macOS code that Processing and py5 both depend on. Hopefully in the future we will find a real fix or a better workaround.
+
+You are seeing this message because this version of py5 has a safety feature that detects the sequence of events that might lead to this crash. However, if you'd like to disable this safety feature (and risk Python crashing), use the following code:
+
+    from py5 import macos_problem
+
+    macos_problem.disable_safety_check()
+
+But before doing that, it would be great if you could do a quick test for us. Please run the following code in a new Jupyter Notebook or IPython REPL, with each line of code executed separately:
+
+    from py5 import macos_problem, test
+
+    macos_problem.disable_safety_check()
+
+    # run a Sketch with the default renderer
+    test.test_java2d()
+
+    # run a Sketch with an opengl renderer
+    # does this cause a crash???
+    test.test_p2d()
+
+Then report your findings to the below GitHub issue thread. Include your macOS version and CPU type. (For your convenience, this information will be displayed at the end of this message.) Your feedback will help us understand the problem better and more accurately calibrate this crash protection feature.
+
+https://github.com/py5coding/py5generator/issues/578
+
+If the above test code doesn't cause Python to crash on your machine, great! You can keep using that `disable_safety_check()` function so you never see this warning again. But please take the time report your findings to the GitHub issue thread. The next version of py5 will incorporate your feedback and the safety feature will be adjusted accordingly.
+
+If the above test code does cause Python to crash on your machine, it's OK. If you really need to mix Java2D and OpenGL renderers together in one Python session, you just need to make sure that the first executed Sketch is always an OpenGL Sketch. For convenience, you can use the following code to open a quick Sketch right after importing py5. This will ensure the first Sketch is always an OpenGL Sketch, eliminating the problem (and this warning) entirely:
+
+    import py5
+    from py5 import test
+
+    test.test_p2d()
+
+If you'd like to read about our progress understanding this issue, please visit the above GitHub issue thread.
+
+Sorry again for the weird limitation. We're doing our best to make py5 as stable as possible. This safety feature is here because we don't want users to become upset because Python crashed for confusing reasons. Thank you for your understanding.
+"""
+
+
+def _macos_safety_check(f):
+    @functools.wraps(f)
+    def decorated(self_, *args):
+        global _first_renderer_opengl
+        if _enforce_safety_check:
+            if _first_renderer_opengl is None:
+                # This is the first Sketch. Record if the renderer is OpenGL.
+                if len(args) >= 3 and args[2] in OPENGL_RENDERERS:
+                    _first_renderer_opengl = True
+                else:
+                    _first_renderer_opengl = False
+
+            elif _first_renderer_opengl is False:
+                # The first Sketch was not OpenGL. OpenGL is not allowed now.
+                if len(args) >= 3 and args[2] in OPENGL_RENDERERS:
+                    self_.println(MESSAGE)
+                    if platform.system() == "Darwin":  # just in case
+                        self_.println("macOS version:", platform.mac_ver()[0])
+                    self_.println("macOS CPU type:", platform.processor())
+                    raise RuntimeError(
+                        "Halting Sketch startup to prevent Python from crashing"
+                    )
+
+        f(self_, *args)
+
+    return decorated

py5/macos_problem.py

@@ -132,6 +132,7 @@
     (('Sketch', 'hue'), ['(rgb: int, /) -> float']),
     (('Sketch', 'image'), ['(img: Py5Image, a: float, b: float, /) -> None', '(img: Py5Image, a: float, b: float, c: float, d: float, /) -> None', '(img: Py5Image, a: float, b: float, c: float, d: float, u1: int, v1: int, u2: int, v2: int, /) -> None']),
     (('Sketch', 'image_mode'), ['(mode: int, /) -> None']),
+    (('Sketch', 'intercept_escape'), ['() -> None']),
     (('Sketch', 'lerp_color'), ['(c1: int, c2: int, amt: float, /) -> int', '(c1: int, c2: int, amt: float, mode: int, /) -> int']),
     (('Sketch', 'light_falloff'), ['(constant: float, linear: float, quadratic: float, /) -> None']),
     (('Sketch', 'light_specular'), ['(v1: float, v2: float, v3: float, /) -> None']),