Python Versions

First off, we should talk about what versions of Python are supported by Processing.py. There are two versions of Python in common use: Python 2 and Python 3. The two versions are very similar, but Python 3 has a number of changes in both syntax and functionality that make it incompatible with previous versions.

Although Python 3 has been available for a number of years, Python 2 remains popular, and many if not most of the Python tutorials and example programs you’re likely to find on the Internet are written with Python 2 in mind. Processing.py itself uses Python 2 internally (in particular, it uses a custom build of Jython 2.5, which is largely compatible with Python 2.7). Keep this in mind when consulting documentation and code samples.

Built-In Function Names

There are a number of built-in Processing functions that share the same name as built-in Python functions. Processing.py does a good job of automatically deciding which of these functions to use, based on the number and kind of parameters passed to the function. But you may occasionally find yourself on the receiving end of error messages or strange behavior when using these functions. The trickiest of these functions are listed here, along with a description of how Processing.py decides which version of the function to call:

set()

The Python built-in function with this name returns a new set object. This function will be called in Processing.py if you provide it with zero parameters or one parameter. Otherwise, the Processing built-in function will be called, which sets a pixel at a particular coordinate on the screen to the given color.

map()

This is a Python built-in function that creates a new list by applying a function call to each item in the list. In Processing, this is a linear interpolation function. If your call to the function has five numeric parameters, Processing.py will call the Processing built-in function; otherwise, the Python built-in will be called.

filter()

In Python, this built-in function creates a copy of a list including only those members for which a given test evaluates to true. In Processing, this is a built-in function that processes on-screen pixels. The Processing version is called if supplied with one or two numeric parameters (including Processing constants identifying filter modes); the Python version is called otherwise.

Colors

Some Processing programmers may be accustomed to specifying colors using a pound symbol, like so: #003399. This syntax does not work in Processing.py. Instead, you can pass a string literal with the same notation to any Processing function that accepts a color. For example:

fill("#003399")
stroke("#FFFFFF")
rect(10, 10, 80, 80)

Python Standard Library

Because Processing.py is just Python under the hood, you can use any module included in Python’s standard library. We took advantage of this fact to use the csv and json libraries in Chapter 12. Using a module in the standard library is easy: simply include an import statement at the beginning of your source code. For example, to use the Python datetime library:

import datetime
# print the current time in ISO8601 format
print datetime.datetime.utcnow().isoformat()

You can find a full list of libraries included with Python here: https://docs.python.org/2.7/library/index.html.

Note that the Python random library shares the same name as the Processing built-in function random. If you import Python’s random library, it will make the Processing random function unavailable in your program.

Processing Libraries and Example Code

The Java implementation of Processing has many helpful libraries, including hundreds of libraries contributed by volunteers and community members. One of the benefits of Processing.py’s Java-based implementation is that most of these libraries will work in your program with little or no modification.

But there’s a problem: you’re likely to find that most Processing libraries you come across have example code for Java Processing only. Fortunately, it’s usually possible to translate simple Java examples to Python with a little bit of know-how and effort.

To demonstrate, here’s the Java example program for Nikolaus Gradwohl’s ttslib library, which makes it easy to add text-to-speech to your Processing sketch. (You can download this library in the Processing IDE by selecting Sketch → Import Library... → Add Library... and then searching for “ttslib” in the Library Manager.) We’ve annotated the code with comments about what needs to be changed to make the example work in Processing.py.

import guru.ttslib.*; // use add_library() instead of import

TTS tts; // don't need to include class type ("TTS")

void setup() { // change to def setup():
  tts = new TTS(); // don't need to use "new" keyword in Python
}

void draw() { // change to def draw():
} // use Python "pass" keyword here to replace empty curly brackets

void mousePressed() { // change to def mousePressed():
  tts.speak("Hi! I am a speaking Processing sketch");
}

Here’s the equivalent code in Python:

add_library('ttslib')

tts = None

def setup():
  global tts
  tts = TTS()

def draw():
  pass

def mousePressed():
  tts.speak("Hi! I am a Processing dot pie sketch")

Many Processing libraries (including the sound library introduced in “Sound”) require a reference to the current PApplet object. In the Java implementation of Processing, you can use the this keyword for this purpose. Python, however, doesn’t have a built-in this keyword, so Processing.py automatically provides a global variable called this that you can pass to libraries that require it.