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:
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:
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:
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:
It has also been added to these
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() 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.
setup() function gets split into the py5-created
setup() functions, the special functions are all moved to
settings(), and everything else, including the global statements, are moved to the new
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
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.
save_frame()methods can now save to an
io.BytesIOobject 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.