release 0.7.2a0

Author: hx2A

README.md

@@ -0,0 +1,67 @@
+# py5
+
+[![py5 downloads](https://pepy.tech/badge/py5/month)](https://pepy.tech/project/py5)
+
+[![Downloads](https://pepy.tech/badge/py5/week)](https://pepy.tech/project/py5)
+
+[![mybinder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/hx2A/py5examples/HEAD?urlpath=lab)
+
+py5 is a new version of [**Processing**][processing] for Python 3.8+. It makes the Java [**Processing**][processing] jars available to the CPython interpreter using [**JPype**][jpype]. It can do just about everything [**Processing**][processing] can do, except with Python instead of Java code.
+
+The goal of py5 is to create a new version of Processing that is integrated into the Python ecosystem. Built into the library are thoughtful choices about how to best get py5 to work with other popular Python libraries such as [numpy](https://www.numpy.org/) or [Pillow](https://python-pillow.org/).
+
+## Simple Example
+
+Here is a simple example of a working py5 Sketch, written in module mode:
+
+```python3
+import py5
+
+
+def setup():
+    py5.size(200, 200)
+    py5.rect_mode(py5.CENTER)
+
+
+def draw():
+    py5.square(py5.mouse_x, py5.mouse_y, 10)
+
+
+py5.run_sketch()
+```
+
+## Installation
+
+If you have Java 17 installed on your computer, you can install py5 using pip:
+
+```bash
+pip install py5
+```
+
+[Detailed installation instructions](https://py5.ixora.io/content/install.html) are available on the documentation website. There are some [Special Notes for Mac Users](https://py5.ixora.io/content/osx_users.html) that you should read if you use OSX.
+
+## Getting Started
+
+There are currently four 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.
+
+The documentation website, [https://py5.ixora.io/](https://py5.ixora.io/), is a work in progress. The reference documentation is solid but the how-to's and tutorials are a work in progress.
+
+[py5generator][py5_generator_repo] is a meta-programming project that creates the py5 library. To view the actual installed py5 library code, look at the [py5 repository][py5_repo]. All py5 library development is done through py5generator.
+
+## Get In Touch
+
+Have a comment or question? We'd love to hear from you! The best ways to reach out are:
+
+* github [discussions](https://github.com/hx2A/py5generator/discussions) and [issues](https://github.com/hx2A/py5generator/issues)
+* twitter [@py5coding](https://twitter.com/py5coding)
+* [processing foundation discourse](https://discourse.processing.org/)
+
+[py5_repo]: https://github.com/hx2A/py5
+[py5_generator_repo]: https://github.com/hx2A/py5generator
+[processing]: https://github.com/processing/processing4
+[jpype]: https://github.com/jpype-project/jpype

README.rst

@@ -82,7 +82,7 @@
     pass
 
 
-__version__ = '0.7.1a6'
+__version__ = '0.7.2a0'
 
 _PY5_USE_IMPORTED_MODE = py5_tools.get_imported_mode()
 
@@ -20172,7 +20172,8 @@ def request_image(image_path: Union[str, Path]) -> Py5Promise:
 def run_sketch(block: bool = None, *,
                py5_options: list[str] = None,
                sketch_args: list[str] = None,
-               sketch_functions: dict[str, Callable] = None) -> None:
+               sketch_functions: dict[str, Callable] = None,
+               _osx_alt_run_method: bool = True) -> None:
     """Run the Sketch.
 
     Parameters
@@ -20275,7 +20276,12 @@ def run_sketch(block: bool = None, *,
 
     _prepare_dynamic_variables(caller_locals, caller_globals)
 
-    _py5sketch._run_sketch(functions, block, py5_options, sketch_args)
+    _py5sketch._run_sketch(
+        functions,
+        block,
+        py5_options,
+        sketch_args,
+        _osx_alt_run_method)
 
 
 def get_current_sketch() -> Sketch:

py5/__init__.py

@@ -225,7 +225,7 @@ def render_frame(draw: Callable, width: int, height: int,
     HelperClass = RenderHelperGraphicsCanvas if use_py5graphics else RenderHelperSketch
     ahs = HelperClass(None, draw, width, height, renderer,
                       draw_args=draw_args, draw_kwargs=draw_kwargs)
-    ahs.run_sketch(block=True)
+    ahs.run_sketch(block=True, _osx_alt_run_method=False)
 
     if not ahs.is_dead_from_error and ahs.output:
         return ahs.output[0]
@@ -325,7 +325,7 @@ def render_frame_sequence(draw: Callable,
     ahs = HelperClass(setup, draw, width, height, renderer, limit=limit,
                       setup_args=setup_args, setup_kwargs=setup_kwargs,
                       draw_args=draw_args, draw_kwargs=draw_kwargs)
-    ahs.run_sketch(block=True)
+    ahs.run_sketch(block=True, _osx_alt_run_method=False)
 
     if not ahs.is_dead_from_error:
         return ahs.output

py5/jars/py5.jar

@@ -61,9 +61,9 @@
     # be aware that __IPYTHON__ and get_ipython() are inserted into the user
     # namespace late in the kernel startup process
     __IPYTHON__  # type: ignore
-    if sys.platform == 'darwin' and get_ipython(
-    ).active_eventloop != 'osx':  # type: ignore
-        print("Importing py5 on OSX but the necessary Jupyter OSX event loop not been activated. I'll activate it for you, but next time, execute `%gui osx` before importing this library.")
+    if sys.platform == 'darwin' and (
+            _ipython_shell := get_ipython()).active_eventloop != 'osx':  # type: ignore
+        print("Importing py5 on OSX but the necessary Jupyter OSX event loop has not been activated. I'll activate it for you, but next time, execute `%gui osx` before importing this library.")
         _ipython_shell.run_line_magic('gui', 'osx')
 except Exception:
     pass
@@ -159,7 +159,8 @@ def __init__(self, *args, **kwargs):
             pass
 
     def run_sketch(self, block: bool = None, *,
-                   py5_options: list = None, sketch_args: list = None) -> None:
+                   py5_options: list = None, sketch_args: list = None,
+                   _osx_alt_run_method: bool = True) -> None:
         """Run the Sketch.
 
         Parameters
@@ -237,13 +238,19 @@ def run_sketch(self, block: bool = None, *,
 
         methods = dict([(e, getattr(self, e)) for e in reference.METHODS if hasattr(
             self, e) and callable(getattr(self, e))])
-        self._run_sketch(methods, block, py5_options, sketch_args)
+        self._run_sketch(
+            methods,
+            block,
+            py5_options,
+            sketch_args,
+            _osx_alt_run_method)
 
     def _run_sketch(self,
                     methods: dict[str, Callable],
                     block: bool,
                     py5_options: list[str] = None,
-                    sketch_args: list[str] = None) -> None:
+                    sketch_args: list[str] = None,
+                    _osx_alt_run_method: bool = True) -> None:
         self._environ = _environ.Environment()
         self.set_println_stream(_DisplayPubPrintlnStream(
         ) if self._environ.in_jupyter_zmq_shell else _DefaultPrintlnStream())
@@ -272,7 +279,31 @@ def _run_sketch(self,
         args = py5_options + [''] + sketch_args
 
         try:
-            _Sketch.runSketch(args, self._instance)
+            if _osx_alt_run_method and platform.system() == 'Darwin':
+                from PyObjCTools import AppHelper
+
+                def run():
+                    _Sketch.runSketch(args, self._instance)
+                    if not self._environ.in_ipython_session:
+                        while not self.is_dead:
+                            time.sleep(0.05)
+                        if self.is_dead_from_error:
+                            surface = self.get_surface()
+                            while not surface.is_stopped():
+                                time.sleep(0.05)
+                        AppHelper.stopEventLoop()
+
+                if block == False and not self._environ.in_ipython_session:
+                    self.println(
+                        "On OSX, blocking is manditory when Sketch is not run through Jupyter. This applies to all renderers.",
+                        stderr=True)
+
+                proxy = jpype.JProxy('java.lang.Runnable', dict(run=run))
+                jpype.JClass('java.lang.Thread')(proxy).start()
+                if not self._environ.in_ipython_session:
+                    AppHelper.runConsoleEventLoop()
+            else:
+                _Sketch.runSketch(args, self._instance)
         except Exception as e:
             self.println(
                 'Java exception thrown by Sketch.runSketch:\n' +
@@ -283,9 +314,9 @@ def _run_sketch(self,
             if (renderer := self._instance.getRendererName()) in [
                     'JAVA2D', 'P2D', 'P3D', 'FX2D']:
                 self.println(
-                    "On OSX, blocking is not allowed in Jupyter when using the",
+                    "On OSX, blocking is not allowed when Sketch using the",
                     renderer,
-                    "renderer.",
+                    "renderer is run though Jupyter.",
                     stderr=True)
                 block = False
 

py5/render_helper.py

@@ -27,4 +27,4 @@
 from . import translators  # noqa
 
 
-__version__ = '0.7.1a6'
+__version__ = '0.7.2a0'

py5/sketch.py

@@ -24,12 +24,6 @@
 from pathlib import Path
 import re
 
-import jpype
-if sys.platform == 'darwin':
-    from PyObjCTools import AppHelper
-else:
-    AppHelper = None
-
 import stackprinter
 
 from . import jvm
@@ -245,22 +239,7 @@ def _run_sketch(sketch_path, classpath, exit_if_error):
         py5_ns = dict()
         py5_ns.update(py5.__dict__)
 
-        def exec_compiled_code():
-            exec(sketch_compiled, py5_ns)
-
-        if sys.platform == 'darwin':
-            def launch_exec_compiled_code():
-                exec_compiled_code()
-                AppHelper.stopEventLoop()
-
-            proxy = jpype.JProxy(
-                'java.lang.Runnable', {
-                    'run': launch_exec_compiled_code})
-            run_sketch_thread = jpype.JClass('java.lang.Thread')(proxy)
-            run_sketch_thread.start()
-            AppHelper.runConsoleEventLoop()
-        else:
-            exec_compiled_code()
+        exec(sketch_compiled, py5_ns)
 
     if new_process:
         p = Process(

py5_tools/__init__.py

@@ -75,7 +75,7 @@ class Py5Kernel(IPythonKernel):
                        *_PY5_HELP_LINKS]).tag(config=True)
 
     implementation = 'py5'
-    implementation_version = '0.7.1a6'
+    implementation_version = '0.7.2a0'
 
 
 class Py5App(IPKernelApp):

py5_tools/imported.py

@@ -51,7 +51,7 @@
 
 
 _CODE_TEMPLATE_END = """
-py5.run_sketch(block=True, sketch_functions=dict(settings=_py5_settings, setup=_py5_setup))
+py5.run_sketch(block=True, sketch_functions=dict(settings=_py5_settings, setup=_py5_setup), _osx_alt_run_method=False)
 if py5.is_dead_from_error:
     py5.exit_sketch()