[schooltool-dev] RFC Time managers and objects that track changes during the term

[Ignas Mikalajunas]

Hi, i have written up some science fiction and would like to get some
feedback before implementing it:

Keyframes, TimeManagers and objects that can track changes
==========================================================

Define the term that will serve as the time manager for the section
(the dates are inclusive):

   >>> term = Term(date(2006, 1, 1), date(2005, 2, 1))

And some objects to play with:

   >>> ann = Person("Ann")
   >>> john = Person("John")
   >>> pete = Person("Pete")

   >>> section = Section()

To track it's changes section needs a time manager set:

   >>> setTimeManager(section, term)

There's a utility that knows what day it is today.

   >>> from zope.component import queryUtility
   >>> sdm = queryUtility(ISchoolDayManager)
   >>> sdm.setSchoolDay(2006, 1, 15)

If we access section directly, we're seeing its state as of the day
that is today according to the ISchoolDayManager

   >>> list(section.members)
   []

We can also modify the section

   >>> section.members.add(john)
   >>> section.members.add(pete)

   >>> list(section.members)
   [John, Pete]

Time machine!

   >>> sdm.setSchoolDay(2006, 1, 14)
   >>> list(section.members)
   []

There's a time viewer as well:

   >>> section2006_1_15 = getObjectForSchoolDay(section, date(2006, 1, 15))
   >>> list(section2006_1_15.members)
   [John, Pete]

These are editable too:

   >>> section2006_1_15.remove(pete)
   >>> list(section2006_1_15.members)
   [John]

getInitialObject is a shortcut for getObjectForSchoolDay(section,
term.first_day).  It is convenient for inializing the object without
worrying bouyt lgobal IWatWasThatUtilityNameAgain urtilities:

   >>> initial_section = getInitialObject(section)
   >>> initial_section.members.add(ann)
   >>> list(initial_section.members)
   [Ann]

Existing views into object state at a given time are updated automatically:

   >>> list(section)
   [Ann]

   >>> list(section2006_1_15)
   [Ann, John]

The time-aware content objects store these state changes in
keyframes.

   >>> kf = IKeyframes(section)

These are accessible with a dict-like interface???, e.g. to see the dates
of changes (in chronological order) use the keys() method:

   >>> kf.keys()
   [date(2006, 1, 1), date(2006, 1, 15)]

You can retrieve both keyframe objects themselves, or the state of the
section that was after that keyframe:


   >>> kf.getKeyframe(date(2006, 1, 15))
   <section_keyframe>

   >>> kf.getState(date(2006, 1, 14))
   <section_before_keyframe>

   >>> kf.getState(date(2006, 1, 15))
   <section_after_keyframe>

   >>> kf[date(2006, 1, 1)]
   <section_keyframe>

   >>> kf[date(2006, 1, 15)]
   <section_keyframe>

A day past the term:

   >>> sdm.setSchoolDay(2007, 1, 14)
   >>> list(section.members)
   [Ann, John, Pete]

   >>> section.members.remove(john)
   Traceback (most recent call last):
   ...
   Exception: You can't modify objects after the last date of their related
   time manager!

A day before the term:

   >>> tm.setSchoolDay(2005, 1, 14)
   >>> list(section.members)
   [Ann]
   >>> section.members.remove(ann)
   >>> list(section.members)
   []

   >>> list(section2007_1_15.members)
   [John, Pete]


Ignas