[Chandler-dev] Reminder refactoring

[Grant Baillie]

Once the tinderboxes have somehow been resurrected from their state  
of wretchedness, I'll be checking in changes to the internals of  
reminders. There's a summary below; a lot of this is in the docstrings.

--Grant

- I split up Reminder functionality into 2 kinds:

   1. osaf.pim.reminders.Reminder, the base kind, which supports  
"absolute"
      (a.k.a. "custom") reminders as before.

   2. osaf.pim.calendar.Calendar.RelativeReminder, which supports  
"relative"
      reminders, including handling recurring events.

   This allows us to resolve some nasty circular dependency issues we  
had
   before: EventStamp depended on Reminder (so as to be able to update
   Reminders when an event's startTime changes, for example), but  
Reminder
   also depended on EventStamp (since relativeTo would default to
   EventStamp.startTime.name).

   In particular, this means we no longer have to have Remindable be an
   Annotation subclass; instead, it's a subclass of ContentItem as it
   was before.

- Before, we had expiredReminders and reminders reflists to track which
   Reminders on a ContentItem were expired. The idea is to have
   one reflist (reminders), and a list of pending reminders. If a  
reminder
   doesn't appear in the "pending" list, it's assumed to have expired if
   it's in the past.

- Each "pending reminder" is an instance of the PendingReminderEntry  
kind. The
   idea is that the Reminders dialog could make a KindCollection of all
   PendingReminderEntries, and display those to the user. (The  
current code
   has a classmethod Reminder.getPendingTuples that does just this, and
   this is used by the UI to display the entries in the dialog).

- There are book-keeping methods and attributes on Reminder to update  
its
   pending list:

      The nextPoll attribute, which is a datetime, tells when the next
      change in the pending reminders list will occur. It starts out as
      None, and is set to Reminder.farFuture when all reminders for this
      Reminder have expired.

      The updatePending() method actually updates the pendingReminder  
reflist,
      and then changes nextPoll if necessary.

- There are changes that that in the future will help us avoid  
generating actual
   Items for (unmodified) occurrences:

     + A Reminder now has at most one Remindable instance, i.e.

         reminderItems = schema.Sequence(Remindable)

       has become

         reminderItem = schema.One(Remindable)

       In the case of recurring events, RelativeReminder handles
       making sure its pendingEntries is updated to point at the correct
       occurrences (i.e. the 'item' PendingReminderEntry attribute won't
       be the master). The plan is to track which occurrence the entry
       pertains to by recurrenceID, rather than by actual Item.

    + Modifications to a master event only get their own reminders  
reflist if
      they have a THIS reminder change.

- Lastly, I left the userReminderTime Calculated attribute on the  
Remindable
   class. The userReminderInterval one, though, only applies to  
EventStamps
   right now, so I moved it there.