How to install and start using py5

[versão em português] [version en español ]

TL:DR;

• To draw and experiment some creative coding with Python follow the instructions below.
• If you are on Windows, try to download and unzip this portanble, double-click thonny.exe and skip to step 4! _{Known Windows issue: If the path to the folder where you keep Thonny with the Java JDK contains non-ASCII characters, this will break jpype and so it will break py5. Try moving Thonny to C:.}

What’s this?

py5 is a library that allows us to use the vocabulary and graphical infrastructure of Processing with the Python programming language (Python 3).

Processing is a Free and Open Source (FLOSS) programming platform started in 2001 by Casey Reas and Ben Fry, widely used by artists and designers, as well as for teaching programming in a visual context. It allows you to generate interactive software with the most diverse purposes and visual interfaces, as well as exporting bitmap/raster images (like PNG and JPG), animations or 2D and 3D vector files (like PDF and SVG, among others). The community enjoys a rich ecosystem of people who produce resources such as teaching examples and freely shared code libraries.

Processing is originally based on the Java programming language, but today there are several projects that develop Processing ideas with other languages, such as p5js with Javascript, Processing Python mode (inside the Processing IDE) using Python 2.7 (Jython), pyp5js using pyodide (a Python in your browser that can talk to p5js), and now py5 with Python 3 (CPython).

To use py5 you will need:

• A Python 3 interpreter (version 3.8 or later);
• The py5 library package and its dependencies (other libraries it needs to work, such as JPype);
• A Java (JDK), which py5 needs for the Processing drawing infrastructure (JPype might look at the JAVA-HOME environment variable to find it);
• Optionally, an IDE (Integrated Development Environment), a code-appropriate text editor that helps you write and run programs. Some people prefer to use py5 on Jupyter Notebooks instead.

To get all these things, this is an overview of the steps I propose and will describe in detail below:

1. Download and install a version of the Thonny IDE that comes with Python 3.10 or greater;
2. Inside Thonny…
   • a. Install the py5 library (using the package manager);
   • b. Install the thonny-py5mode plug-in (using the extension manager);
3. Let the thonny-py5mode plug-in download and configure the JDK for you;
4. Check if everything is working, run a small example!
5. (Extra) Learn about the difference betweeen imported mode and module mode.

Another way to get everything you need, if these steps fail for any reason, is to follow the instructions at the py5 documentation, starting with installing miniconda, which comes with Python and the conda package manager, to install py5, and then following the instructions for installing and setting up Java (JDK).

1. Download and install the Thonny IDE

• For Windows:

  • Try to download and unzip this portanble, double-click thonny.exe and skip to step 4!
  • or a Thonny installer from the repository releases

• For MacOS: also get an installer from the repository releases

• For Linux: find a package from the repository releases or run the bash script installer

2a. Install the py5 library

Open, select Tools > Manage packages… from the menu…

Search for py5 and click on the install button.

2b. Install the thonny-py5mode plug-in

Open, select Tools > Manage plug-ins… from the menu…

Search for thonny-py5mode and click on the install button.

You need to restart Thonny after this step!!!

3. Allow the thonny-py5mode plug-in to download the Java JDK

Once restarted, a new py5 menu should appear in Thonny’s interface, click on the py5 > Imported mode for py5 menu option and then click OK in the dialog window that appears.

When you first select this, the plug-in will download, extract and configure the JDK for you (in Thonny’s user-config directory). This process can be quite lengthy depending on your connection, but it only happens the first time you select the menu option.

Thonny’s window may appear frozen as it downloads and configures the JDK, don’t despair!**

A message will appear when it is finished.

You can apply recommended py5 settings to make a few configuration tweaks to your IDE, including enabling the blue Kianite theme!

4. Run a small example, to check everything is working!

With the py5 > imported mode for py5 option on, you can run the following code using the green arrow button or CTRL+R (COMMAND+R on a Mac). Creative coders usually call their programs sketches.

def setup():
    size(300, 200)
    rect_mode(CENTER)

def draw():
    square(mouse_x, mouse_y, 10)

If you have trouble geting your program to execute, try stopping any other execution that is still running.

5. (Extra) Learn about the difference between imported mode and module mode

What is the imported mode feature provided by the thonny-py5mode plug-in?

The thonny-py5mode plug-in creates a py5 menu in the Thonny interface, inside the py5 menu, there is an Imported mode for py5 option that can be turned on or off. When Imported mode for py5 is on you can write your sketches in a simplified maner, called imported mode. It works by making Thonny run your code using the py5 sketch runner, a special tool that can also be called from the command line if you are not using Thonny.

Important note: The imported mode option is not appropriate for executing Python code that doesn’t make use of the py5 library!

In imported mode the vocabulary of py5, that is, the names of functions, constants and system variables (such as the mouse position), are available without the py5. prefix (needed on module mode, more about it later), and your program will be automatically executed by the run_sketch function from py5.

With imported mode on, you can also run static mode sketches, that is, programs without animation or interactivity because they do not have a draw() function defined.

What is module mode and how can I use it?

When you disable the imported mode for py5 menu option, you return Thonny to the normal behavior for executing any Python code.

In this case, you can use py5 in module mode, which is how most Python libraries are handled, i.e. importing the library at the beginning of the program with import, and calling its functions with the library name as a prefix.

import py5

def setup():
    py5.size(300, 200)
    py5.rect_mode(py5.CENTER)

def draw():
    py5.square(py5.mouse_x, py5.mouse_y, 10)

py5.run_sketch()

Note that you will need to use import py5 at the beginning of your code, and py5.run_sketch() at the end, as well as the py5. prefix for all functions, constants and variables offered by the py5 library.

Useful resources for using py5

• official py5 documentation py5
• examples in Jupyter Notebooks
• tabreturn’s py5 quick reference
• The py5 discussions forum on GitHub
• The py5 category at the Processing Foundation Forum

Acknowledgments

Very special thanks to Jim, creator of py5, the maintainers of Thonny IDE, and tabreturn who made the thonny-py5mode plugin, which makes installing and using py5 much easier, most of the step-by-step part and all the images came from the installing intructions at his page, I just added some context and comments!

Alexandre B A Villares (abav.lugaralgum.com), CC-BY-NC-SA-4.0 License