zc.generationalset 0.4.0

High-level usage pattern

• Define a tree of sets representing the data in an application. This may be user specific.

• Clients make updates via REST calls to a server. They don’t make local changes except in response to server updates.

• Client requests include their data generation.

• Most (JSON) responses to server calls have optional updates property that contains generational updates since the generation provided by the client. When the client gets updates, which include the new generation, it applies the updates to it’s internal data store.

• For native apps, the server sends push notifications when there are updates for a user and, in response, the client polls for the updates. This allows updates to be extremely timely without constant polling.

Note that this package only provides the data structure implementation. Wrapping the data structure in a REST interface or sending notifications is up to applications.

API

Every object in a GSet must have an id. By default, this is provided by an id attribute, but you can configure a GSet to use another attribute or some other mechanism to get an id for an object.

When an object is added to a GSet, call the add method on the Gset with the object:

>>> from zc.generationalset import GSet
>>> things = GSet()
>>> athing = Thing(42)
>>> things.add(athing)

When an object is changed, call the changed method on the Gset with the object. If object is not present in the Gset, update will raise a KeyError:

>>> things.changed(athing)
>>> things.changed(Thing(43))
Traceback (most recent call last):
...
KeyError: 43

>>> things.generational_updates(0)
{'generation': 3, 'adds': [Thing(42)]}

To remove an object, call the remove method with the object:

>>> things.remove(athing)

To get updates to a set since a given generation, call generational_updates, passing a generation:

>>> things.generational_updates(0)
{'generation': 4, 'removals': [42]}

>>> things.add(Thing(1))
>>> things.generational_updates(0)
{'generation': 5, 'removals': [42], 'adds': [Thing(1)]}
>>> things.generational_updates(3)
{'generation': 5, 'adds': [Thing(1)]}

Note that generations start at 1.

The result of calling generational_updates is a dictionary with keys:

generation

The current generation of the set

adds

Objects added since the given generation.

removals

Ids of objects removed since the given generation.

contents

All of the object in the set.

contents are returned when there have been many removals since the given generation. A generational set only keeps track of a limited number (99 by default, but configurable) of removals. If a client is too out of date for the set to have relevant removals, it returns the entire contents, instead of returning adds and removals.

GSets support iteration, and querying length and containment. They don’t currently support set operations, like intersection and union. You can also retrieve an item from a GSet using its id:

>>> len(things)
1
>>> list(things)
[Thing(1)]
>>> Thing(1) in things
True
>>> things[1]
Thing(1)

0.4.0 (2017-06-20)

• Python 3 support

• When asking for updates from generation 0, only adds are sent. Never removals, making this common case more efficient.

0.3.0 (2014-08-28)

• Added a changed method to make intent clear when simply recording changes.

• Fixed: exceptions were raised when objects added to generational sets quacked a little like generational sets.

0.2.0 (2014-08-10)

• Improved subset APIs:

  • No longer need to specify superset flag.

  • Can have set and non-set children.

  • A subset can be created without a parent and the parent will be set when it’s added to a containing set.

0.1.2 (2014-06-09)

Fixed: Internal data structures were misshandled when there were more

than the maximum number of removals.

(Release 0.1.1 was made in error.)

0.1.0 (2014-06-08)

Initial release