PyTables User's Guide: Hierarchical datasets in Python - Release 1.3.3
Prev | Chapter 3. Tutorials | Next

# 3.5. Exercising the Undo/Redo feature

`PyTables` has integrated support for undoing and/or redoing actions. This functionality lets you put marks in specific places of your hierarchy manipulation operations, so that you can make your HDF5 file pop back (undo) to a specific mark (for example for inspecting how your hierarchy looked at that point). You can also go forward to a more recent marker (redo). You can even do jumps to the marker you want using just one instruction as we will see shortly.

You can undo/redo all the operations that are related to object tree management, like creating, deleting, moving or renaming nodes (or complete sub-hierarchies) inside a given object tree. You can also undo/redo operations (i.e. creation, deletion or modification) of persistent node attributes. However, when actions include internal modifications of datasets (that includes `Table.append`, `Table.modifyRows` or `Table.removeRows` among others), they cannot be undone/redone currently.

This capability can be useful in many situations, like for example when doing simulations with multiple branches. When you have to choose a path to follow in such a situation, you can put a mark there and, if the simulation is not going well, you can go back to that mark and start another path. Other possible application is defining coarse-grained operations which operate in a transactional-like way, i.e. which return the database to its previous state if the operation finds some kind of problem while running. You can probably devise many other scenarios where the Undo/Redo feature can be useful to you [1].

## 3.5.1. A basic example

In this section, we are going to show the basic behavior of the Undo/Redo feature. You can find the code used in this example in `examples/tutorial3-1.py`. A somewhat more complex example will be explained in the next section.

First, let's create a file:

    >>> import tables
    >>> fileh = tables.openFile("tutorial3-1.h5", "w", title="Undo/Redo demo 1")

And now, activate the Undo/Redo feature with the method `enableUndo` (see [here]) of `File`:

    >>> fileh.enableUndo()

From now on, all our actions will be logged internally by `PyTables`. Now, we are going to create a node (in this case an `Array` object):

    >>> one = fileh.createArray('/', 'anarray', [3,4], "An array")

Now, mark this point:

    >>> fileh.mark()
    1
    >>>

We have marked the current point in the sequence of actions. In addition, the `mark()` method has returned the identifier assigned to this new mark, that is 1 (mark #0 is reserved for the implicit mark at the beginning of the action log). In the next section we will see that you can also assign a name to a mark (see [here] for more info on `mark()`). Now, we are going to create another array:

    >>> another = fileh.createArray('/', 'anotherarray', [4,5], "Another array")

Right. Now, we can start doing funny things. Let's say that we want to pop back to the previous mark (that whose value was 1, do you remember?). Let's introduce the `undo()` method (see [here]):

    >>> fileh.undo()
    >>>

Fine, what do you think it happened? Well, let's have a look at the object tree:

    >>> print fileh
    do-undo1.h5 (File) 'Undo/Redo demo 1'
    Last modif.: 'Fri Mar  4 20:22:28 2005'
    Object Tree:
    / (RootGroup) 'Undo/Redo demo 1'
    /anarray (Array(2,)) 'An array'

    >>>

What happened with the `/anotherarray` node we've just created? You guess it, it has disappeared because it was created after the mark 1. If you are curious enough you may well ask where it has gone. Well, it has not been deleted completely; it has been just moved into a special, hidden, group of PyTables that renders it invisible and waiting for a chance to be reborn.

Now, unwind once more, and look at the object tree:

    >>> fileh.undo()
    >>> print fileh
    do-undo1.h5 (File) 'Undo/Redo demo 1'
    Last modif.: 'Fri Mar  4 20:22:28 2005'
    Object Tree:
    / (RootGroup) 'Undo/Redo demo 1'

    >>>

Oops, `/anarray` has disappeared as well!. Don't worry, it will revisit us very shortly. So, you might be somewhat lost right now; in which mark are we?. Let's ask the `getCurrentMark()` method (see [here]) in the file handler:

    >>> print fileh.getCurrentMark()
    0

So we are at mark #0, remember? Mark #0 is an implicit mark that is created when you start the log of actions when calling `File.enableUndo()`. Fine, but you are missing your too-young-to-die arrays. What can we do about that? `File.redo()` (see [here]) to the rescue:

    >>> fileh.redo()
    >>> print fileh
    do-undo1.h5 (File) 'Undo/Redo demo 1'
    Last modif.: 'Fri Mar  4 20:22:28 2005'
    Object Tree:
    / (RootGroup) 'Undo/Redo demo 1'
    /anarray (Array(2,)) 'An array'

    >>>

Great! The `/anarray` array has come into life again. Just check that it is alive and well:

    >>> fileh.root.anarray.read()
    [3, 4]
    >>> fileh.root.anarray.title
    'An array'
    >>>

Well, it looks pretty similar than in its previous life; what's more, it is exactly the same object!:

    >>> fileh.root.anarray is one
    True

It just was moved to the the hidden group and back again, but that's all! That's kind of fun, so we are going to do the same with `/anotherarray`:

    >>> fileh.redo()
    >>> print fileh
    do-undo1.h5 (File) 'Undo/Redo demo 1'
    Last modif.: 'Fri Mar  4 20:22:28 2005'
    Object Tree:
    / (RootGroup) 'Undo/Redo demo 1'
    /anarray (Array(2,)) 'An array'
    /anotherarray (Array(2,)) 'Another array'

    >>>

Welcome back, `/anotherarray`! Just a couple of sanity checks:

    >>> assert fileh.root.anotherarray.read() == [4,5]
    >>> assert fileh.root.anotherarray.title == "Another array"
    >>> fileh.root.anotherarray is another
    True

Nice, you managed to turn your data back into life. Congratulations! But wait, do not forget to close your action log when you don't need this feature anymore:

    >>> fileh.disableUndo()

That will allow you to continue working with your data without actually requiring `PyTables` to keep track of all your actions, and more importantly, allowing your objects to die completely if they have to, not requiring to keep them anywhere, and hence saving process time and space in your database file.

## 3.5.2. A more complete example

Now, time for a somewhat more sophisticated demonstration of the Undo/Redo feature. In it, several marks will be set in different parts of the code flow and we will see how to jump between these marks with just one method call. You can find the code used in this example in `examples/tutorial3-2.py`

Let's introduce the first part of the code:

    import tables

    # Create an HDF5 file
    fileh = tables.openFile('tutorial3-2.h5', 'w', title='Undo/Redo demo 2')

             #'-**-**-**-**-**-**- enable undo/redo log  -**-**-**-**-**-**-**-'
    fileh.enableUndo()

    # Start undoable operations
    fileh.createArray('/', 'otherarray1', [3,4], 'Another array 1')
    fileh.createGroup('/', 'agroup', 'Group 1')
    # Create a 'first' mark
    fileh.mark('first')
    fileh.createArray('/agroup', 'otherarray2', [4,5], 'Another array 2')
    fileh.createGroup('/agroup', 'agroup2', 'Group 2')
    # Create a 'second' mark
    fileh.mark('second')
    fileh.createArray('/agroup/agroup2', 'otherarray3', [5,6], 'Another array 3')
    # Create a 'third' mark
    fileh.mark('third')
    fileh.createArray('/', 'otherarray4', [6,7], 'Another array 4')
    fileh.createArray('/agroup', 'otherarray5', [7,8], 'Another array 5')

You can see how we have set several marks interspersed in the code flow, representing different states of the database. Also, note that we have assigned names to these marks, namely `'first'`, `'second'` and `'third'`.

Now, start doing some jumps back and forth in the states of the database:

    # Now go to mark 'first'
    fileh.goto('first')
    assert '/otherarray1' in fileh
    assert '/agroup' in fileh
    assert '/agroup/agroup2' not in fileh
    assert '/agroup/otherarray2' not in fileh
    assert '/agroup/agroup2/otherarray3' not in fileh
    assert '/otherarray4' not in fileh
    assert '/agroup/otherarray5' not in fileh
    # Go to mark 'third'
    fileh.goto('third')
    assert '/otherarray1' in fileh
    assert '/agroup' in fileh
    assert '/agroup/agroup2' in fileh
    assert '/agroup/otherarray2' in fileh
    assert '/agroup/agroup2/otherarray3' in fileh
    assert '/otherarray4' not in fileh
    assert '/agroup/otherarray5' not in fileh
    # Now go to mark 'second'
    fileh.goto('second')
    assert '/otherarray1' in fileh
    assert '/agroup' in fileh
    assert '/agroup/agroup2' in fileh
    assert '/agroup/otherarray2' in fileh
    assert '/agroup/agroup2/otherarray3' not in fileh
    assert '/otherarray4' not in fileh
    assert '/agroup/otherarray5' not in fileh

Well, the code above shows how easy is to jump to a certain mark in the database by using the `goto()` method (see [here]).

There are also a couple of implicit marks for going to the beginning or the end of the saved states: 0 and -1. Going to mark #0 means go to the beginning of the saved actions, that is, when method `fileh.enableUndo()` was called. Going to mark #-1 means go to the last recorded action, that is the last action in the code flow.

Let's see what happens when going to the end of the action log:

    # Go to the end
    fileh.goto(-1)
    assert '/otherarray1' in fileh
    assert '/agroup' in fileh
    assert '/agroup/agroup2' in fileh
    assert '/agroup/otherarray2' in fileh
    assert '/agroup/agroup2/otherarray3' in fileh
    assert '/otherarray4' in fileh
    assert '/agroup/otherarray5' in fileh
    # Check that objects have come back to life in a sane state
    assert fileh.root.otherarray1.read() == [3,4]
    assert fileh.root.agroup.otherarray2.read() == [4,5]
    assert fileh.root.agroup.agroup2.otherarray3.read() == [5,6]
    assert fileh.root.otherarray4.read() == [6,7]
    assert fileh.root.agroup.otherarray5.read() == [7,8]

Try yourself going to the beginning of the action log (remember, the mark #0) and check the contents of the object tree.

We have nearly finished this demonstration. As always, do not forget to close the action log as well as the database:

             #'-**-**-**-**-**-**- disable undo/redo log  -**-**-**-**-**-**-**-'
    fileh.disableUndo()

    # Close the file
    fileh.close()

You might want to check other examples on Undo/Redo feature that appear in `examples/undo-redo.py`.

### Notes

[1] | You can even hide nodes temporarily. Will you be able to find out how?

Prev | Home | Next
Multidimensional table cells and automatic sanity checks | Up | Using enumerated types