[Dev] ContentModel, Calendar, Contacts, etc. reorganization/flattening

[Phillip J. Eby]

One of the 0.6 developer platform goals is to flatten our Python package 
hierarchy a bit, so as to make things easier to find, type, access, and 
remember the names of.  Part of this is also switching to naming 
conventions that are similar to other Python projects of similar size, like 
Twisted, Zope, etc.  The first such flattening we'd like to do is to 
reorganize the osaf.contentmodel package as follows:

Old name(s)                                New names(s)
-----------------------------------------  -------------------
osaf.contentmodel.ContentModel.*        -> osaf.pim.items.*
osaf.contentmodel.calendar.Calendar.*   -> osaf.pim.calendar.*
osaf.contentmodel.calendar.Recurrence.* -> osaf.pim.recurrence.*
osaf.contentmodel.contacts.Contacts.*   -> osaf.pim.contacts.*
osaf.contentmodel.mail.Mail.*           -> osaf.pim.mail.*
osaf.contentmodel.photos.Photo.*        -> osaf.pim.photos.*
osaf.contentmodel.tasks.Task.*          -> osaf.pim.tasks.*

As you can see, this basically means we'll be removing five directories, 
moving their contents up a level, and renaming them.  The new naming 
convention is that all module or package names are all-lowercase, and will 
usually be plural in order to avoid confusion with class names (which 
usually have an initial capital letter and are singular).

One of the benefits of this change will be making it easier to access many 
kind classes from CPIAScript and the "headless" tool without creating 
alternate addressing schemes.  These tools can simply "from osaf import 
pim", and then use e.g. ``pim.Note`` etc. to access the needed classes, etc.

There should be no semantic effects of this move, as we are not making any 
changes to anything *in* the modules being moved.  Currently, the plan is 
to make these changes next week, and then begin reviewing the resulting 
schema the following week for general cleanup (which should be a bit easier 
to do with the flattened structure.)

Please note that if this reorganization would negatively affect the 
schedule of anything you're working on in the above parcels (or in a parcel 
that uses them), please contact me as soon as practical so we can 
co-ordinate the timing of the move to avoid interfering with your 
work.  Also, if you have any questions about the reorganization (or object 
to it!), please let me know.

One other move that will be taking place, and probably first, is that the 
CurrentPointer class is being renamed to Reference, and moved to the 
application.Parcel package.  It's also likely that existing CurrentPointer 
instances will undergo some name changes, and the osaf.current parcel is 
going away.  This is part of our attempt to solidify an addressing scheme 
for "well-known" objects in Chandler, and to update our policies regarding 
what data goes in //parcels and what goes in the "soup" (currently called 
//userdata).

Historically, the distinction between these two repository trees has been 
read-only vs. read-write; read-only data has been historically put in 
//parcels, and everything else in //userdata.  However, there's a growing 
consensus that this isn't quite the right distinction, and that instead of 
read-only vs. read-write, the distinction could and should be "well-known, 
nameable item or reference" vs. "anonymous items".  In other words, items 
(or references to items) owned by a parcel could indeed be read-write, if 
it makes sense.

For example, the All, In, Out, and Trash collections are well-known 
objects, in that they must exist for Chandler to run, and there is code and 
data that has to reference them at some known location.  If the distinction 
between parcels and "the soup" is just a question of naming, then it makes 
sense for some parcel to create and own these collections, even though the 
items that are *in* the collections reside in the soup.

Sometimes, however, a parcel just needs to *refer* to an item by a 
well-known name, even though the item itself is anonymous.  For example, 
the "me" contact, the "current" account, and so on.  In these cases, a 
parcel will create a Reference whose ``item`` attribute points to the 
actual item in the soup, while the Reference itself lives in the 
parcel.  Reference objects will therefore be used in place of 
CurrentPointer objects, and the inverse relationship of ``item`` will be 
``references``.  This means that any personal parcels that now define a 
``currentItemOf`` will need to be changed to use ``references`` 
instead.  There will be a separate posting to announce this change when it 
happens, which will give more details.

By the way, if you missed my Tuesday post about "Easier access to parcel 
contents", you might want to have another look.  The feature described 
there is an important part of the above change, because it gives us a 
uniform addressing scheme for named items that need to be referenced by 
code.  The addressing is based on Python module name, rather than on 
repository paths or namespace URLs, and provides a convenient way to access 
a specific parcel's contents from code.  It's also much faster than using 
findPath() or similar operations.

There has also been some discussion about renaming //userdata (perhaps to 
//soup) to avoid continuing confusion about what that root is used 
for.  //soup more clearly indicates that this is just a soup of anonymous 
items, and doesn't carry any misleading implication that it's only for the 
user's data or the only place for read-write data.  "userdata" is mentioned 
only about 30 or so times in the entire Chandler codebase, so such a change 
would be relatively simple, but it hasn't been finalized yet.