pyp5js

pyp5js: Python to P5.js Transcriptor

PyPI version Continuous Integration Gitpod ready-to-code

Processing ideas and Python 3 together with P5.js in the browser, using Transcrypt.

This project started from a proof of concept based in Axel Tanner’s “Transcrypt & p5js” blogpost. The source code in this Github repo.

The project’s main goal was to use Tanner’s approach combined with decorator and global variables control to enable P5.js API from being called “directly” from the Python code as clean as possible.

pyp5js covers all the methods, variables and event handlers listed in the p5.js API documentation. Here’s an example of a valid Python code using p5.js API:

from pyp5js import *


def setup():
    createCanvas(200, 200)
    background(160)


def draw():
    fill("blue")
    background(200)
    radius = sin(frameCount / 60) * 50 + 50
    ellipse(100, 100, radius, radius)

Examples

Click here to see a list of examples generated with pyp5js.

Installation

This project requires Python 3 and is now on PyPI, so you can install it with pip or pip3, depending on your environment:

$ pip install pyp5js

(You might have to install setuptools first, if it’s not already installed)

Quickstart

Since you’ll be writting Python code and then generating the correspondent P5.js code from it, pyp5js provides a web application interface to help you to generate the files.

So, to start a the application, you’ll have to run:

$ pyp5js serve

Then point your browser to http://localhost:5000/ and create a new sketch via the browser by filling the form with the name of your sketch. This command will compile the sketches on the fly, so after changing/saving the sketch file you just need to reload the page on your browser. It’ll also guide you on which file you have to edit the Python code and how to see it running after you save it.

pyp5js will create a new directory in your home called sketchbook-pyp5js. If you don’t want to save your sketch in this default directory, you can set the environment variable SKETCHBOOK_DIR to point to the directory you want to use. Or you can also run the serve command as:

$ SKETCHBOOK_DIR='~/my-custom-sketchbook' pyp5js serve

Now, have fun =]

Internals details

The web application is an interface to reduce barriers on playing around with pyp5js to newcomers and people who don’t feel confortable with the terminal interface. But if you want to use the terminal, pyp5js also exposes a CLI.

So, to start a new sketch, you’ll have to run:

$ pyp5js new my_sketch

This command will create a directory with the following code structure using p5.js 1.0.0:

~ my_sketch/
  ~ static /
    - p5.js
  - index.html
  - my_sketch.py

The index.html is prepared to display your sketch, so you’ll have to keep it open in your browser (I really advise you to use Firefox) to see results from the code you’ll add to my_sketch.py.

To see your app on your browser you’ll need to run a Web server (opening the “index.html” file directly won’t work since it is disabled by default) - we packaged it already for you, just run:

$ pyp5js serve

If you just want to compile your code (without running the Web server) there’s the transcrypt command:

$ pyp5js transcrypt my_sketch

If you’re lazy as me, you can use the monitor command instead of the previous one. The command will monitor your sketch directory and keep track of any changes on any .py files. When it notices a new change, it automatically runs the transcrypt process for you:

$ pyp5js monitor my_sketch

You can also use the monitor command within the new by running:

$ pyp5js new my_sketch --monitor

All of the command-line interface methods have a few optional arguments, such as specifying the sketch directory. You can check them by running:

$ pyp5js --help

Known issues, differences to the Processing.Py and P5.js ways of doing things and limitations

How can I contribute?

Testing, testing and testing

Since pyp5js have a lot of moving parts, it would be great to have the p5.js API fully covered and tested. So, use your imagination, code your sketches and, if pyp5js breaks or starts to annoy you with something, you’re very welcome to open an issue documenting your thoughts. Test it and let me know how can I improve it.

What about these shinning examples?

If you fell confortable with that, I’d be happy to add some of your pyp5js sketches to our examples list! To do so, you’ll have to fork this repository and add your new sketch example in the docs/examples directory. Once you’ve your sketch ready, you can open a pull request and I’ll take a look at it.

I want to hack!

Okay, if you want to contribute with pyp5js’s code, let’s go! I really advise you to use virtualenv with virtualenvwrapper or pyenv to isolate your pyp5js fork from the rest of your system. Once you have everything ready, you can run:

$ git clone git@github.com:YOUR_GITHUB_PROFILE/pyp5js.git
$ mkvirtualenv pyp5js -p /usr/bin/python3  # python3 path can change depending on your system
$ cd pyp5js
$ pip install -r dev-requirements.txt
$ python setup.py develop
$ make test

After that, you should have the pyp5js command enabled and it will respect all the changes you introduce to the code. Now, a brief explanation about the code under pyp5js directory:

Now go fetch yourself an issue and happy hacking!