Skip to main content

A python package exposing the memento design pattern

Project description

Recollection Overview

Recollection is a state recalling system. It allows for state of objects to be snap-shotted exposing functionality to then 'rollback' to any previously stored state.

Recollection gives two distinctly different exposures of this mechanism. If performance is not the most critical concern and your focus is on code simplicity then the inheritence approach is possibly your best option providing you have ownership of the classes which need historical state.

Note: This is currently pre-release


You can install this using pip:

pip install xcomposite

Alternatively you can get the source from:

Recollection Inheritence (Inference)

This example shows how to setup a class using inheritence to automatically handle state storing. As you can see from the example, there is no need to explicitly ask recollection to store at any time as it is handled entirely for you :

import recollection

# -- Inference is the recollection class designed specifically
# -- for inheritence situations.
class Foo(recollection.Inference):

    def __init__(self):
        super(Foo, self).__init__()

        # -- Demonstrate a private attribute with getter
        # -- and setter methods
        self._letter = 1

        # -- Demonstrate public attributes which should be
        # -- stored whenever they are changed
        self.number = 10

        # -- Because we're inheriting from the Inference class, any
        # -- registered properties will automatically trigger a
        # -- state store whenever they are changed.

    # -- Declare that this is a recollection getter
    def letter(self):
        return self._letter

    # -- Declare this as a recollection setter, using the same
    # -- label as the getter. Whenever setHeight is called
    # -- it will automatically store the state change.'foobar')
    def setLetter(self, value):
        self._letter = value

# -- Instance our object
foo = Foo()

# -- Update our variable using our accessor - which will automatically
# -- incur a state store
for letter in ['a', 'b', 'c', 'd', 'e']:

# -- Demonstrate that the current state is 'e'
print(foo.letter())  # -- Prints 'e'

# -- Roll back one setp and demonstrate that the property
# -- now evaluates to 'd'
print(foo.letter())  # -- Prints 'd'

# -- Here we demonstrate directly changing properties
# -- which are registered
foo.number = 5
foo.number = 99
print(foo.number == 99)

# -- Now restore back one step
print(foo.number == 5)

Memento Stack

However, we do not always have the luxury of changing class inheritance or you may specifically want to keep the recollection state management out of your actual inheritance hierarchy. The following examples all demonstrate how this can be achieved.

In this example we have a class with two properties. We the instance a Memento class targeting our foo instance. Each time we call the store method within Memento we are taking a snapshot of the values returned by the registered properties/functions

import recollection

class Foo(object):
    def __init__(self): = 'bar'
        self.i = 0

# -- Instance our object
foo = Foo()

# -- Instance a memento object pointing at foo
stack = recollection.Memento(foo)

# -- Start changing some values on foo, and
# -- ask our stack to store those changes
for i in range(11):
    foo.i = i

    # -- Ask the memento object to store the state

# -- Printing i, shows us 10

# -- But lets say we roll back to the state 5 versions
# -- ago

# -- Now we can see i is at the version it was when
# -- it was stored 5 versions back

Lock-Stepped Storage

It also allows multiple Memento objects to be put into a lock-step, such that whenever one memento object is storing or restoring then all other memento objects in that sync group will also store or restore.

import recollection

class Foo(object):
    def __init__(self): = 'bar'
        self.i = 0

# -- This time we instance two completely seperate
# -- foo objects
foo_a = Foo()
foo_b = Foo()

# -- Instance a memento stack for each
stack_a = recollection.Memento(foo_a)
stack_b = recollection.Memento(foo_b)

stack_a.register(['name', 'i'])
stack_b.register(['name', 'i'])

# -- Now we will put our stacks into a state of lock-step
# -- which means whenever one of them is stored or restored
# -- all others in the lock-step group will have the same
# -- action performed

# -- Increment some values on both objects
for i in range(11):
    foo_a.i = i
    foo_b.i = i

    # -- Trigger a store on only one stack

# -- We can see that both A and B have a value of 10
print(foo_a.i == 10 and foo_b.i == 10)

# -- Now we rollback - knowing that this action will occur
# -- across all grouped memento objects

# -- Now we can see i is at the version it was when
# -- it was stored 5 versions back
print(foo_a.i == 5 and foo_b.i == 5)


Serialisers can also be registered against memento instances allowing the stored state of a memento object to be serialised into a persistent state.

This example shows how we might define a user preferences class, and within that class we define a memento object to store the preference state. By registering a serialiser the preferences state will be written to disk whenever the 'store' is called.

Notice that in this example we're also choosing not to store private member variables, but instead we're harnessing the public api of the class as getters and setters.

class UserPreferences(object):

    def __init__(self):

        # -- Visual preferences
        self._theme = 'default'

        # -- Define our memento, which we utilise specifically to
        # -- store our preferences to a persistent location
        self._stack = recollection.Memento(self)

        # -- We will utilise the JSON Appdata serialiser, which
        # -- writes our memento information to the app data system
        # -- location

        # -- Register which properties we want the store to focus on

        # -- Finally, we deserialise - which will update this class
        # -- with any previously stored state

    # --------------------------------------------------------------
    def get_theme(self):
        return self._theme

    # --------------------------------------------------------------
    def set_theme(self, theme):
        self._theme = theme


Equally, if we want to make it a little more obvious at the class level which functions are storing we could opt to utilise the Memento decorator, which stores and serialises:

from memento import Memento

class UserPreferences(object):

    def set_theme(self, theme):
        self._theme = theme


Here we see an example of state being used as a roll-back feature, which is particularly useful when allowing users to interact with data:

import recollection

class Foo(object):

    def __init__(self):
        self._x = 10
        self._y = 20

        self._stack = recollection.Memento(self)
        self._stack.register(['_x', '_y',])

        # -- Store the default state

    def x(self):
        return self._x

    def setX(self, value):
        self._x = value

    def y(self):
        return self._x

    def setY(self, value):
        self._y = value

    def undo(self):

# -- Instance our foo object and print the default
# -- value
foo = Foo()
print('Default Value : %s' % foo.x())
        Default Value : 10

# -- Set the value to 200
print('Changed Value : %s' % foo.x())
        Changed Value : 200

# -- Undo the last action, and print that we're not back
# -- to a value the same as the default
print('Back to the default value after undo : %s' % foo.x())
        Back to the default value after undo : 10


These mechanics are demonstrated in the example modules, specifically:

User Preferences Object

# -- This demo shows a user preferences object being interacted
# -- which which works in the same way as the example above.
from recollection.examples.userprefs.demo import demo


Alternate User Preferences Object

# -- This demo shows a user preferences object being interacted
# -- which which works by decorating setter properties
from recollection.examples.userprefs.demo import demo2


Board Game with roll-back

# -- This demo utilises a 'boardgame' style scenario where
# -- we're given two players and the desire to 'undo' the results
# -- of turns if they are not desirable!
from import demo


Pin Movement (Multi-attribute altering)

# -- This demo utilises a 'boardgame' style scenario where
# -- we're given two players and the desire to 'undo' the results
# -- of turns if they are not desirable!
from recollection.examples.pins.demo import demo


Testing and Stability

There are currently unittests which cover most of Memento's core, but it is not yet exhaustive.


This has been tested under Python 2.7.13 and Python 3.6.6 on both Ubuntu and Windows.


If you would like to contribute thoughts, ideas, fixes or features please get in touch!

Project details

Download files

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

Files for recollection, version 0.9.0
Filename, size File type Python version Upload date Hashes
Filename, size recollection-0.9.0-py3-none-any.whl (36.7 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size recollection-0.9.0.tar.gz (29.3 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page