This is an extension to the Kivy framework that adds a system for programming with statecharts. It is a port of Michael Cohen's Ki framework, which became SproutCore.statechart.
Original Ki repo https://github.com/frozenCanuck/ki
SC.Statechart repo https://github.com/sproutcore/sproutcore/tree/master/frameworks/statechart
SC.Statechart was used as the basis for this port to Python.
A virtual environment works well for Kivy and kivy-statecharts development. But if you have Kivy already running locally and wish to take a quick look at kivy-statecharts, clone kivy-statecharts and cd to its examples directory, and to the hello_world example. If you simply run python main.py, kivy-statecharts will not be found, because it is not on PYTHONPATH. You can augment paths on PYTHONPATH on the command line as described in the answers for this Stackoverflow question about PYTHONPATH. So the following should bring up the hello_world example app:
PYTHONPATH=/path/to/kivy_statecharts python main.py
The hello_world app appears to do nothing, but if you type letters for "hello world", (h, e, l, o, w, r, d), you will see buttons with these letters appear in random locations. If you click or touch any button, even more random buttons will appear. When you look at the hello_world example app code, you will see one real state in a simple statechart. There are bindings to fire action events to the statechart with h, e, l, o, w, r, and d keyboard entries, and for the same events to be fire when buttons are clicked. The action events correspond to methods of the single state in the statechart. We would say that the current state has action methods that handle the keyboard action events. A statechart is an organization structure holding states with such actions and helper methods.
From the hello_world example app, you can move to the Balls example app, and to the more involved examples from there. deflectouch_with_statecharts is the most complete example so far.
If you are debugging or adding features to kivy-statecharts, here is one way to work with it. Make a virtualenv for doing kivy-statechart work:
virtualenv kivy_statecharts cd kivy_statecharts source bin/activate
Also, here are steps using the virtualenvwrapper system, which is a nice way to work, because you can switch between virtualenvs easily:
mkvirtualenv kivy_statecharts cdvirtualenv workon kivy_statecharts
Either way, whether by using virtualenv directly, or by using virtualenvwrapper, you now have a kivy_statecharts virtualenv, and it should be active. For Unix systems, to make sure that you have it activated, you can check which python is active with:
which python
and you should see the path to the python in your virtualenv, not to the system Python interpreter.
Do steps to install kivy; if using master, install dependencies, then git clone it, and inside kivy, do:
python setup.py develop
Clone the kivy-statecharts repo:
git clone https://github.com/kivy/kivy-statecharts.git cd kivy_statecharts python setup develop python setup dev (for setting up for testing)
Be warned: This addon is in alpha state. Use it at your own risk.
Source Sphinx docs are in the docs directory.
See the examples.
kivy-statecharts is perhaps becoming suitable for use in production
environments, judging by a good set of tests, but not yet by any known apps in
the wild (as of April, 2013). A proper release program will be started in
Summer 2013 so that, to use, you can make sure to pin the exact version in your
requirements. It is expected that releases, although they will start with an
alpha designation, will soon move to beta status. The main reason for the
present status is that despite a full set of tests, there aren't yet enough
examples covering fuller treatments of some of the features and uses.
Contributions to kivy-statecharts are very welcome. Just clone its GitHub
repository and submit your contributions as pull requests.
Note that all development is done on the develop branch. master is reserved
for "production-ready state". Therefore, make sure to always base development work
on the current state of the develop branch.
This follows the highly recommended A successful Git branching model pattern, which is implemented by the excellent gitflow git extension.
kivy-statecharts has 100% test coverage. Use nose or py.test.
Please make sure that you add tests for new features and that all tests pass before
submitting pull requests. Running the test suite is as easy as running py.test
from the source directory. Presently, both py.test and nosetests work. Run
python setup.py dev to have all the test requirements installed in your virtualenv.
Unit tests have previously been done with nose. In the kivy_statechart directory, run:
nosetests
As of April 2012, most tests were ported from the original javascript version.