Skip to main content

Redis based Finite State Machine.

Project description

Finist
======

Redis based Finite State Machine.

Description
-----------

Finist is a finite state machine that is defined and persisted in
[Redis][redis].

Community
---------

Meet us on IRC: [#lesscode](irc://chat.freenode.net/#lesscode) on
[freenode.net](http://freenode.net/).

Related projects
----------------

* [Finist implemented in Lua][finist.lua]
* [Finist implemented in Ruby][finist.lua]
* [Finist implemented in Rust][finist.ruby]

Getting started
---------------

Install [Redis][redis]. On most platforms it's as easy as grabbing
the sources, running make and then putting the `redis-server` binary
in the PATH.

Once you have it installed, you can execute `redis-server` and it
will run on `localhost:6379` by default. Check the `redis.conf`
file that comes with the sources if you want to change some settings.

Usage
-----

Finist requires a Redis [Python Redis] compatible client. To make things
easier, `redic` is listed as a runtime dependency so the examples
in this document will work.

```python
from finist import Finist
import redis
redis_conn = redis.Redis()

# Initialize with a Redis client, the name of the machine and the
# initial state. In this example, the machine is called "order" and
# the initial status is "pending". The Redis client is connected to
# the default host (127.0.0.1:6379).
machine = Finist(redis_conn, "order", "pending")

# Available transitions are defined with the `on` method
# `machine.on(<event>, <initial_state>, <final_state>)`
machine.on("approve", "pending", "approved")
machine.on("cancel", "pending", "cancelled")
machine.on("cancel", "approved", "cancelled")
machine.on("reset", "cancelled", "pending")
```

Now that the possible transitions are defined, we can check the
current state:

```python
machine.state()
# => "pending"
```

And we can trigger an event:

```python
machine.trigger("approve")
# => ["approved", true]
```

The `trigger` method returns an array of two values: the first
represents the current state, and the second represents whether
a transition occurred.

Here's what happens if an event doesn't cause a transition:

```python
machine.trigger("reset")
# => ["approved", false]
```

Here's a convenient way to use this flag:

```python
state, changed = machine.trigger("reset")

if changed
print "State changed to %s\n" %state
```

If you need to remove all the transitions for a given event, you
can use `rm`:

```python
machine.rm("reset")
```

Note that every change is persisted in Redis.

Representation
--------------

Each event is represented as a hash in Redis, and its field/value
pairs are the possible transitions.

For the FSM described in the examples above, the keys are laid out
as follows:

```ini
# Current state
finist:order (string)

# Transitions for event `approve`
finist:order:approve (hash)
pending -> approved

# Transitions for event `cancel`
finist:order:cancel (hash)
pending -> cancelled
approved -> cancelled

# Transitions for event `reset`
finist:order:reset (hash)
cancelled -> pending
```

Installation
------------

```
$ python setup.py install
or
$ pip install finist
```

[redis]: http://redis.io
[Python Redis]: https://github.com/andymccurdy/redis-py
[finist.lua]: https://github.com/soveran/finist.lua
[finist.rust]: https://github.com/badboy/finist
[finist.ruby]: https://github.com/soveran/finist

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
finist-0.1.2.tar.gz (3.7 kB) Copy SHA256 hash SHA256 Source None

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page