release 0.4a2

Author: hx2A

README.rst

@@ -6,8 +6,9 @@ py5 is a new version of Processing_ for Python 3.8+. It makes the Processing_ Ja
 This entire repository is created by the meta-programming project py5generator_. Therefore, this code should not be edited manually. Any issues, etc, should be directed to the py5generator_ repository.
 
 The `py5 documentation website 
-<http://py5.ixora.io/>`_ provides basic tutorials and reference documentation.
+<http://py5.ixora.io/>`_ provides basic tutorials and reference documentation. See py5examples_ for example code.
 
 .. _Processing: https://github.com/processing/processing4
 .. _JPype: https://github.com/jpype-project/jpype
 .. _py5generator: https://github.com/hx2A/py5generator
+.. _py5examples: https://github.com/hx2A/py5examples

py5/__init__.py

@@ -23,12 +23,11 @@
 """
 import sys
 from pathlib import Path
-import logging
 import inspect
 from typing import overload, Any, Callable, Union, Dict, List, Tuple  # noqa
 from nptyping import NDArray, Float, Int  # noqa
 
-import json  # noqa
+# import json  # noqa
 import numpy as np  # noqa
 from PIL import Image  # noqa
 from jpype import JClass  # noqa
@@ -62,12 +61,10 @@
     pass
 
 
-__version__ = '0.4a1'
+__version__ = '0.4a2'
 
 _PY5_USE_IMPORTED_MODE = py5_tools.imported.get_imported_mode()
 
-logger = logging.getLogger(__name__)
-
 java_conversion.init_jpype_converters()
 
 
@@ -18944,6 +18941,80 @@ def list_threads() -> None:
     """
     return _py5sketch.list_threads()
 
+##############################################################################
+# module functions from print_tools.py
+##############################################################################
+
+
+def set_println_stream(println_stream: Any) -> None:
+    """Customize where the output of ``println()`` goes.
+
+    Parameters
+    ----------
+
+    println_stream: Any
+        println stream object to be used by println method
+
+    Notes
+    -----
+
+    Customize where the output of ``println()`` goes.
+
+    When running a Sketch asynchronously through Jupyter Notebook, any ``print``
+    statements using Python's builtin function will always appear in the output of
+    the currently active cell. This will rarely be desirable, as the active cell
+    will keep changing as the user executes code elsewhere in the notebook. The
+    ``println()`` method was created to provide users with print functionality in a
+    Sketch without having to cope with output moving from one cell to the next. Use
+    ``set_println_stream`` to change how the output is handled. The
+    ``println_stream`` object must provide ``init()`` and ``print()`` methods, as
+    shown in the example. The example demonstrates how to configure py5 to output
+    text to an IPython Widget.
+    """
+    return _py5sketch.set_println_stream(println_stream)
+
+
+def println(
+    *args,
+    sep: str = ' ',
+    end: str = '\n',
+        stderr: bool = False) -> None:
+    """Print text or other values to the screen.
+
+    Parameters
+    ----------
+
+    args
+        values to be printed
+
+    end: str = '\\n'
+        string appended after the last value, defaults to newline character
+
+    sep: str = ' '
+        string inserted between values, defaults to a space
+
+    stderr: bool = False
+        use stderr instead of stdout
+
+    Notes
+    -----
+
+    Print text or other values to the screen. For a Sketch running outside of a
+    Jupyter Notebook, this method will behave the same as the Python's builtin
+    ``print`` method. For Sketches running in a Jupyter Notebook, this will place
+    text in the output of the cell that made the ``run_sketch()`` call.
+
+    When running a Sketch asynchronously through Jupyter Notebook, any ``print``
+    statements using Python's builtin function will always appear in the output of
+    the currently active cell. This will rarely be desirable, as the active cell
+    will keep changing as the user executes code elsewhere in the notebook. This
+    method was created to provide users with print functionality in a Sketch without
+    having to cope with output moving from one cell to the next.
+
+    Use ``set_println_stream()`` to customize the behavior of ``println()``.
+    """
+    return _py5sketch.println(*args, sep=sep, end=end, stderr=stderr)
+
 ##############################################################################
 # module functions from sketch.py
 ##############################################################################
@@ -19376,10 +19447,10 @@ def run_sketch(block: bool = None, *,
     functions will be used to actualize your Sketch.
 
     Use the ``block`` parameter to specify if the call to ``run_sketch()`` should
-    return immediately or block until the Sketch exits. If the ``block`` parameter
-    is not specified, py5 will first attempt to determine if the Sketch is running
-    in a Jupyter Notebook or an IPython shell. If it is, ``block`` will default to
-    ``False``, and ``True`` otherwise.
+    return immediately (asynchronous Sketch execution) or block until the Sketch
+    exits. If the ``block`` parameter is not specified, py5 will first attempt to
+    determine if the Sketch is running in a Jupyter Notebook or an IPython shell. If
+    it is, ``block`` will default to ``False``, and ``True`` otherwise.
 
     A list of strings passed to ``py5_options`` will be passed to the Processing
     PApplet class as arguments to specify characteristics such as the window's
@@ -19394,13 +19465,26 @@ def run_sketch(block: bool = None, *,
     ``sketch_functions`` parameter to pass a dictionary of the desired callable
     functions. The ``sketch_functions`` parameter is not available when coding py5
     in class mode. Don't forget you can always replace the ``draw()`` function in a
-    running Sketch using ``hot_reload_draw()``."""
+    running Sketch using ``hot_reload_draw()``.
+
+    When running a Sketch asynchronously through Jupyter Notebook, any ``print``
+    statements using Python's builtin function will always appear in the output of
+    the currently active cell. This will rarely be desirable, as the active cell
+    will keep changing as the user executes code elsewhere in the notebook. As an
+    alternative, use py5's ``println()`` method, which will place all text in the
+    output of the cell that made the ``run_sketch()`` call. This will continue to be
+    true if the user moves on to execute code in other Notebook cells. Use
+    ``set_println_stream()`` to customize this behavior. All py5 error messages and
+    stack traces are routed through the ``println()`` method. Be aware that some
+    error messages and warnings generated inside the Processing Jars cannot be
+    controlled in the same way, and may appear in the output of the active cell or
+    mixed in with the Jupyter Kernel logs."""
     if block is None:
         block = not _in_ipython_session
 
     sketch_functions = sketch_functions or inspect.stack()[1].frame.f_locals
     functions = dict([(e, sketch_functions[e])
-                      for e in reference.METHODS if e in sketch_functions and callable(sketch_functions[e])])
+                     for e in reference.METHODS if e in sketch_functions and callable(sketch_functions[e])])
 
     if not set(functions.keys()) & set(['settings', 'setup', 'draw']):
         print(("Unable to find settings, setup, or draw functions. "

py5/custom_exceptions.py

@@ -41,7 +41,7 @@ def handle_typeerror(exc_type_name, exc_msg, py5info):
             else:
                 exc_msg += 'Your parameters must match one of the following signatures:\n'
                 exc_msg += '\n'.join([' * ' + fname +
-                                      sig for sig in signatures])
+                                     sig for sig in signatures])
 
     return exc_msg
 

py5/jars/core.jar

@@ -18,11 +18,8 @@
 #
 # *****************************************************************************
 import sys
-import logging
 from pathlib import Path
 from collections import defaultdict
-from io import StringIO
-from contextlib import redirect_stderr, redirect_stdout
 from typing import Union
 import line_profiler
 
@@ -35,9 +32,6 @@
 
 _JavaNullPointerException = JClass('java.lang.NullPointerException')
 
-logger = logging.getLogger(__name__)
-
-
 # *** stacktrace configuration ***
 # set stackprinter color style. Default is plaintext. Other choices are darkbg,
 # darkbg2, darkbg3, lightbg, lightbg2, lightbg3.
@@ -52,28 +46,30 @@
 }
 
 
-def _exception_msg(exc_type_name, exc_msg, py5info):
+def _exception_msg(println, exc_type_name, exc_msg, py5info):
     try:
         msg = _EXCEPTION_MSGS.get(exc_type_name, exc_msg)
         if isinstance(msg, str):
             return msg
         elif callable(msg):
             return msg(exc_type_name, exc_msg, py5info)
         else:
-            logger.error(
-                f'unknown exception msg type for {exc_type_name}: {type(msg).__name__}')
+            println(
+                f'unknown exception msg type for {exc_type_name}: {type(msg).__name__}',
+                stderr=True)
             return exc_msg
     except Exception as e:
-        logger.error(
-            f'error generating exception msg for {exc_type_name}: {e}')
+        println(
+            f'error generating exception msg for {exc_type_name}: {e}',
+            stderr=True)
         return exc_msg
 
 
 def register_exception_msg(exc_type_name: str, msg: Union[str, callable]):
     _EXCEPTION_MSGS[exc_type_name] = msg
 
 
-def handle_exception(exc_type, exc_value, exc_tb):
+def handle_exception(println, exc_type, exc_value, exc_tb):
     py5info = []
     try:
         if _prune_tracebacks and hasattr(exc_tb, 'tb_next'):
@@ -92,8 +88,9 @@ def handle_exception(exc_type, exc_value, exc_tb):
             if trim_tb:
                 trim_tb.tb_next = None
     except Exception as e:
-        logger.critical(
-            f'Exception thrown while examining error traceback: {str(e)}')
+        println(
+            f'Exception thrown while examining error traceback: {str(e)}',
+            stderr=True)
 
     errmsg = stackprinter.format(
         thing=(exc_type, exc_value, exc_tb.tb_next),
@@ -106,22 +103,21 @@ def handle_exception(exc_type, exc_value, exc_tb):
         errmsg = errmsg.replace(
             str(exc_value),
             _exception_msg(
+                println,
                 exc_type.__name__,
                 str(exc_value),
                 py5info))
 
-    logger.critical(errmsg)
+    println(errmsg, stderr=True)
 
     sys.last_type, sys.last_value, sys.last_traceback = exc_type, exc_value, exc_tb
 
 
 @JImplements('py5.core.Py5Methods')
 class Py5Methods:
 
-    def __init__(self, sketch, _stream_redirect=None):
+    def __init__(self, sketch):
         self._sketch = sketch
-        self._stream_redirect = _stream_redirect
-
         self._functions = dict()
         self._pre_hooks = defaultdict(dict)
         self._post_hooks = defaultdict(dict)
@@ -186,28 +182,6 @@ def get_function_list(self):
 
     @JOverride
     def run_method(self, method_name, params):
-        if self._stream_redirect:
-            return self._stream_redirect_run_method(method_name, params)
-        else:
-            return self._run_method(method_name, params)
-
-    def _stream_redirect_run_method(self, method_name, params):
-        stdout, stderr = StringIO(), StringIO()
-
-        with redirect_stdout(stdout), redirect_stderr(stderr):
-            retval = self._run_method(method_name, params)
-
-        stdout_val = stdout.getvalue()
-        if stdout_val:
-            self._stream_redirect('stdout', stdout_val)
-
-        stderr_val = stderr.getvalue()
-        if stderr_val:
-            self._stream_redirect('stderr', stderr_val)
-
-        return retval
-
-    def _run_method(self, method_name, params):
         try:
             if method_name in self._functions:
                 # first run the pre-hooks, if any
@@ -224,17 +198,21 @@ def _run_method(self, method_name, params):
                         hook(self._sketch)
             return True
         except Exception:
-            handle_exception(*sys.exc_info())
+            handle_exception(self._sketch.println, *sys.exc_info())
             self._sketch._terminate_sketch()
             return False
 
+    @JOverride
+    def py5_println(self, text, stderr):
+        self._sketch.println(text, stderr=stderr)
+
     @JOverride
     def shutdown(self):
-        logger.info('shutdown initiated')
         try:
             self._sketch._shutdown()
             self._is_terminated = True
             self.terminate_hooks()
-            logger.info('shutdown complete')
         except Exception:
-            logger.exception('exception in sketch shutdown sequence')
+            self._sketch.println(
+                'exception in sketch shutdown sequence',
+                stderr=True)

py5/jars/py5.jar

@@ -21,3 +21,4 @@
 from .data import DataMixin  # noqa
 from .threads import ThreadsMixin  # noqa
 from .pixels import PixelMixin  # noqa
+from .print_tools import PrintlnStream, _WidgetPrintlnStream, _DefaultPrintlnStream, _DisplayPubPrintlnStream  # noqa