Help Test py5 Release 0.6.0-alpha.1

In an effort to improve the py5 release process, I am making the next release available on github for testing before I package and deploy it to PyPI.

Install py5 0.6.0-alpha.1

Here's the command you'll need to install py5 from github:

pip install git+https://github.com/hx2A/py5.git@0.6.0-alpha.1#egg=py5

This needs to be done after the other py5 installation tasks (as explained in the documentation) are completed. The simplest way to go about this is to create a working py5 environment and then run the above command. Don't forget to install the py5 and py5bot kernels, and don't forget to check the version number:

>>> import py5
>>> py5.__version__
'0.6.0-alpha.1'

Since py5's github repositories are split between the py5generator and py5 repositories, there are a bunch of extra steps one must take to install the development version of py5. The only person who uses the development build is me. Moving forward I need to come up with a way to change this so that more people can provide helpful feedback before a release.

Development Documentation Website

There is a development documentation website available at http://py5dev.ixora.io/. The relevant changes to the documentation are found there. This will be pushed to the production website when the actual release takes place.

What Needs To Be Tested

Here are the major points that I would like people to focus on:

Context Managers

You can now use methods like begin_shape() as context managers:

def setup():
    py5.no_stroke()
    with py5.begin_shape():
        py5.vertex(20, 20)
        py5.vertex(40, 20)
        py5.vertex(40, 40)

Previously you would have to write code like this:

def setup():
    py5.no_stroke()
    py5.begin_shape()
    py5.vertex(20, 20)
    py5.vertex(40, 20)
    py5.vertex(40, 40)
    py5.end_shape()

This context manager functionality has been added to these methods:

  • begin_raw()

  • begin_record()

  • begin_shape()

  • begin_closed_shape()

  • begin_contour()

  • push_matrix()

  • begin_camera()

  • push_style()

  • push()

It has also been added to these Py5Graphics methods:

  • begin_draw()

  • begin_raw()

  • begin_shape()

  • begin_closed_shape()

  • begin_contour()

  • push_matrix()

  • begin_camera()

  • push_style()

  • push()

And these Py5Shape methods:

  • begin_shape()

  • begin_closed_shape()

  • begin_contour()

This context manager functionality is one of many great ideas found in processing.py. Several members of the py5 community who have experience using processing.py asked that this functionality be added to py5 also. I've been using it for a month now and love it. Ideas and feedback like this contribute much to py5, so please keep them coming! And many thanks to the processing.py team for coming up with this idea.

Example code for each using this context manager feature is available on the development documentation website http://py5dev.ixora.io/. I'm not going to link to it directly because if the documentation website is organized properly, you should be able to easily find it. So perhaps this is a test of the documentation website as well. :)

Global Statements in setup()

The user's setup() method will now allow global statements to appear before calls to size(). This fixes issue #40.

If you create a setup() function and don't create a settings() function, your setup() function will be inspected to search for calls to methods like size() that are really supposed to be in settings(). If they are found, py5 will dissect your code and create a settings() function for you. The rule for this was that the calls to these methods must be at the very beginning of your setup() function, ignoring comments.

In Python the best practice for using global statements is to put them in the very beginning of the function. That convention was conflicting with the implementation of the above functionality. Now the rule is that calls to methods like size() must be at the beginning of your setup() function, ignoring comments and global statements.

When your setup() function gets split into the py5-created settings() and setup() functions, the special functions are all moved to settings(), and everything else, including the global statements, are moved to the new setup() function.

If you need a visual, here is a concrete example. If you write the below code:

x = None

def setup():
    """setup is called once at the beginning of the sketch"""
    global x
    py5.size(200, 200)
    x = 42
    print('in setup')

Your code will be transformed to the equivalent of this:

x = None

def settings():
    py5.size(200, 200)


def setup():
    """setup is called once at the beginning of the sketch"""
    global x
    x = 42
    print('in setup')

Observe that a new function settings() was created and the call to size() was moved from setup() to settings(). Previously the global statement was tripping up the code transformation.

Rebuilt py5bot, run_sketch, and py5 Magics

This version makes non-trivial changes to the internal execution mechanisms behind the py5bot kernel, the run_sketch command line utility, and the py5 Magics such as %%py5draw. These changes had to be made to fix issue #44. The functionality should be the same as before, just without that bug.

While doing this, I also made improvements to the error messages. In all cases, the stack traces should never contain any hint of Java or py5's own code. For some errors that isn't possible, but that is the goal. Errors should only include code written by the user and correctly point to the part of the code that has the problem. Anything less than that is confusing and unhelpful to beginners. Actually accomplishing this has been a major task over the past year and will likely continue long into the future.

All of this is similar to how the IPython kernel presents coding errors to users. When exceptions are thrown, you never see any hint of the kernel's internal code. Don't take that for granted! I've studied the IPython kernel's code extensively and have applied what I learned to py5.

Windows and OSX

I do almost all of my development on Linux. I have Windows and OSX machines available and do testing on them, but often miss things. Historically there have been a lot of platform specific problems on those two machines.

Other Things That Changed

  • Update to Processing 4.0 beta 2 jars

  • py5bot now supports the SVG and PDF renderers. To use either, specify your desired renderer in your call to the size() method, such as size(200, 200, SVG, '/tmp/test.svg'). Both require you to provide a filename to save the renderered SVG or PDF file to. Since PDF files cannot be embedded in Jupyter Notebooks, you won't see displayed output like you do for other renderers. SVG output, however, will appear in the notebook.

  • The save() and save_frame() methods can now save to an io.BytesIO object instead of writing to disk. As an aside, note that both methods are using the Pillow image library to save images, so the methods support any image format that that library supports.

  • There are new utilities for translating processing.py code to py5 imported mode code and utilities for translating between imported mode and module mode. I'll explain these in more detail later.

  • This version number 0.6.0-alpha.1 is following a different version naming convention than the previous 0.5a2. I want py5 to conform to proper semantic versioning standards.

Comments