[Dev] Parcel namespaces and the schema API

[Phillip J. Eby]

While working today on integrating the fledgling Python Schema API with the 
parcel loading system, I discovered that there are three parcels that do 
not conform to the current convention for specifying parcel namespaces:

     FAIL: core http://osafoundation.org/parcels/core
       OK: osaf.contentmodel
       OK: osaf.contentmodel.mail
       OK: osaf.contentmodel.calendar
       OK: osaf.contentmodel.contacts
       OK: osaf.contentmodel.tasks
       OK: osaf.framework.sharing
       OK: osaf.framework.blocks
       OK: osaf.framework.wakeup
     FAIL: examples.zaobao.schema 
http://osafoundation.org/examples/zaobao/schema
       OK: osaf.framework.blocks.detail
       OK: osaf.views.main
       OK: osaf.framework.blocks.calendar
       OK: osaf.framework.attributeEditors
       OK: osaf.framework.webserver
       OK: osaf.framework.webserver.servlets.blog
       OK: osaf.framework.webserver.servlets.photos
       OK: osaf.views.repositoryviewer
       OK: osaf.views.demo
       OK: osaf.examples.zaobao.blocks
       OK: osaf.current
     FAIL: osaf.framework.webserver.servers 
http://osafoundation.org/parcels/osaf/framework/webserver/servers
       OK: osaf.mail

Of these, the problem with 'core' and 'osaf/framework/webserver/servers' is 
simply that they lack an __init__.py, making them not parcels.  The problem 
with ZaoBao is that it creates a custom namespace, for no apparent 
reason.  I'm guessing that it's probably either some sort of legacy code 
issue, or else it was intended as an example for other parcel developers 
not to use a namespace URI under NS_ROOT ("http://osafoundation.org/parcels").

As a practical matter, however, using a custom namespace URI doesn't 
provide a parcel developer with any real benefit, versus simply following 
the existing convention.  This is because parcels' top-level directory name 
is already required to be unique -- both because the repository paths are 
based on directory names, and because Python package namespaces don't 
overlap the way Java namespace packages do.  I can't create a parcel whose 
top-level directory name is 'osaf', no matter what XML namespace I 
use!  So, it would seem that eliminating the extra step of defining a 
parcel namespace would help to further reduce parcel development overhead.

Therefore, I propose to formalize the existing state of affairs by making a 
parcel's namespace equal to 
"http://osafoundation.org/parcels/path/to/parcel", such that changing 
'path/to/parcel' to 'path.to.parcel' will allow you to import the Python 
package or module that corresponds to the parcel.  This means two minor 
changes to the existing setup:

   * The '<namespace>' tag in parcel.xml would be deprecated and phased out

   * Parcel directories would be required to contain an __init__.py, or 
else a module of the correct name must exist in the parent parcel (e.g. the 
presence of 'blocks.py' in 'examples/zaobao' means that no 
'examples/zaobao/blocks/__init__.py' is needed.)

Per discussion with Morgen, I am going to go ahead and begin phasing in the 
uncontroversial parts of this proposal.  First, I'm adding empty 
'__init__.py' files where needed, and making ZaoBao's namespaces conform to 
the convention used by all other parcels.  Second, I'll add default 
namespace support to application.Parcel so that the remaining two uses of 
'<namespace>' can also be removed.  None of these changes should affect 
existing code or parcels in any way, but will enable integration of the 
Schema API with the parcel loader.

At that point, if '<namespace>' can be given an adequate deprecation period 
for third parties to update any parcels currently using it, it should be 
possible to eliminate one of the parcel loader's three passes over 
parcel.xml files, which should result in some degree of performance 
improvement for parcel loading.  Currently, the '__scanParcels()' pass is 
only needed because of the need to process '<namespace>'; Morgen and I 
believe that the processing of '<namespaceMap>' can then be moved to the 
'__loadParcel()' pass, thereby eliminating one full round of XML parsing 
for each parcel.xml file.

Removing <namespace> is of course the potentially controversial bit, so if 
you know of any reasons why it should remain, or have any input as to what 
the deprecation period before its removal should be, please respond.  Thanks!