8. Development

The main GitHub repository for the project can be found at:

Anyone is more than welcome to open tickets to discuss bugs, new features, or just to ask usage questions (I find this useful for gauging what questions ought to feature in the FAQ, for example).

Even if you don’t feel up to hacking on the code, I’d love to hear suggestions from people of what you’d like the API to look like!

8.1. Development installation

If you wish to develop pisense itself, it is easiest to obtain the source by cloning the GitHub repository and then use the “develop” target of the Makefile which will install the package as a link to the cloned repository allowing in-place development (it also builds a tags file for use with vim/emacs with Exuberant’s ctags utility, and links the Sense HAT’s customized RTIMULib into your virtual environment if it can find it). The following example demonstrates this method within a virtual Python environment:

$ sudo apt install lsb-release build-essential git git-core \
    exuberant-ctags virtualenvwrapper python-virtualenv python3-virtualenv

After installing virtualenvwrapper you’ll need to restart your shell before commands like mkvirtualenv will operate correctly. Once you’ve restarted your shell, continue:

$ cd
$ mkvirtualenv -p /usr/bin/python3 pisense
$ workon pisense
(pisense) $ git clone https://github.com/waveform80/pisense.git
(pisense) $ cd pisense
(pisense) $ make develop

To pull the latest changes from git into your clone and update your installation:

$ workon pisense
(pisense) $ cd ~/pisense
(pisense) $ git pull
(pisense) $ make develop

To remove your installation, destroy the sandbox and the clone:

(pisense) $ deactivate
$ rmvirtualenv pisense
$ rm -fr ~/pisense

8.2. Building the docs

If you wish to build the docs, you’ll need a few more dependencies. Inkscape is used for conversion of SVGs to other formats, Graphviz is used for rendering certain charts, and TeX Live is required for building PDF output. The following command should install all required dependencies:

$ sudo apt install texlive-latex-recommended texlive-latex-extra \
    texlive-fonts-recommended graphviz inkscape gnuplot

Once these are installed, you can use the “doc” target to build the documentation:

$ workon pisense
(pisense) $ cd ~/pisense
(pisense) $ make doc

The HTML output is written to build/html while the PDF output goes to build/latex.

8.3. Test suite

If you wish to run the pisense test suite, follow the instructions in Development installation above and then make the “test” target within the sandbox:

$ workon pisense
(pisense) $ cd ~/pisense
(pisense) $ make test

A tox configuration is also provided that will test the library against all supported Python and numpy versions. Be aware that this can take some considerable time on first run (when the venvs are being created), even on a fast machine. Subsequent runs will be quicker but you may wish to consider using the “-p” option for parallelism:

$ workon pisense
(pisense) $ cd ~/pisense
(pisense) $ pip install tox
(pisense) $ tox -p auto

Measuring the extremes, on a reasonable Core i7 machine:

  • An initial run, creating the venvs with no parallelism, takes >10 minutes.
  • A subsequent run, re-using the existing venvs with the auto-parallel option takes ~30 seconds.

You can expect your own tox runs to come in somewhere within the boundaries, depending on the parameters you use, and whether or not you’re re-using existing vens.


If developing under Ubuntu, the `Dead Snakes PPA`_ is particularly useful for obtaining additional Python installations for testing.