[Zope3-dev] The Zope Software Certification Program and Common Repository Proposal

[Stephan Richter]

On Tuesday 21 February 2006 12:14, Lennart Regebro wrote:
> ...for a maintainer. I also completely fail to see how the latter
> format gives anybody any extra insight, or how this provides any sort
> of documentation.

Of course this does not provide any benefit, because you did not document the 
steps at all. Here is how I would document this:

  The migration also handles quarterly recurring events. The first step is to 
create a calendar

  >>> caltool = self.portal.portal_cpscalendar
  >>> mgrcal = caltool.getHomeCalendarObject(manager_id)

and add an event to it that is repeating qurterly:

  >>> event = Event('quarterly',
  ...                    title="This is a quarterly event",
  ...                    attendees=None,
  ...                    from_date=DateTime(2005, 4, 1, 8, 0),
  ...                    to_date=DateTime(2005, 4, 1, 10, 0),
  ...                    event_type='event_recurring',
  ...                    recurrence_period='period_quarterly')
  >>> mgrcal._setObject('quarterly', event)

[In the following part I do not understand why you have an if statement. That 
smells fishy for a test. In fact, if the if statement is false, the test will 
fail.]
We also need to make sure that the CPS Shared Calendar tool is registered with 
the CMF.

  >>> if 'install_cpssharedcalendar' not in self.portal.objectIds():
  ...          script = ExternalMethod('install_cpssharedcalendar', '',
  ...                                  'CPSSharedCalendar.install',
  ...                                  'install')
  >>> self.portal._setObject('install_cpssharedcalendar', script)
  >>> script = self.portal['install_cpssharedcalendar']
  >>> script()
  >>> transaction.commit()

Note: It was important to commit the transaction at this point, so that the 
objects are assigned an oid and are correctly indexed.

[This part of the test will also fail, if the condition is false; or even 
worse, if the condition is false, but the previous condition was true, it 
will fail in unexpected ways, because you reuse the same "script" variable.]

If a migration script is provided, then install it as a tool as well.

  >>> if 'migrate_cpscalendar' not in self.portal.objectIds():
  ...      script = ExternalMethod('migrate_cpscalendar', '',
  ...                                  'CPSSharedCalendar.upgrade',
  ...                                  'migrate_from_cpscalendar')
  >>> self.portal._setObject('migrate_cpscalendar', script)
  >>> script = self.portal['migrate_cpscalendar']
  >>> script()

[I have no clue what the storage manager has to do with the calendar. This 
would require some explanation as well.]

Once all the tools are registered, we can use the storage manager utility to 
retrieve the event:

  >>> sm = zapi.getUtility(IStorageManager, context=self.portal)
  >>> event = sm.getEvent('quarterly')

As you can see, the event is recurring every three months (or quarterly):

  >>> recurrence = event.recurrence
  >>> interfaces.IMonthlyRecurrenceRule.providedBy(recurrence)
  True
  >>> recurrence.interval
  3
  >>> recurrence.until
  None

Some comments about the code above. While writing the documentation, I noticed 
that

(1) this test makes no sense, since you are never using the variable `mgrcal`,

(2) a lot of magic is happening, because it is not obvious at all how the 
event goes from the calendar to the storage manager utility.

Even if this test is correct as shown, the two points above would need a lot 
of explaining for someone to understand what's going on there.


> (btw, through all this, I assume that Jims fix for the doctest
> debugging problem that he mentioned did work, and that you now can
> insert an import pdb;pdb.set_trace() in the middle of the doctests.
> Right?)

This has been fixed since ages. :-)

Regards,
Stephan
-- 
Stephan Richter
CBU Physics & Chemistry (B.S.) / Tufts Physics (Ph.D. student)
Web2k - Web Software Design, Development and Training