[Distutils] Using namespace packages? READ THIS

[Phillip J. Eby]

Conversely, if you're not using namespace packages with setuptools, you 
don't need to read this.  Remain calm, everything is fine.  :)  If you do 
use them, please read on.  Most of what's in here will probably not affect 
most people anyway, even if they do use namespace packages.  But just take 
a few moments to check and make sure these issues don't apply to you.

I just checked in a fix for the issue with namespace packages in system 
package installation scenarios.  This fix unfortunately puts some 
significant limitations on what you can have in a namespace package 
__init__.py.

Basically, *all* you should have in *every* namespace package __init__.py is:

     __import__('pkg_resources').declare_namespace(__name__)

because the __init__.py files are now *not installed* when using --root or 
--single-version-externally-managed.  So anything else you put in these 
files, is just not going to work in that case.

Now, if you're doing what the ll-libs were doing, where you have one 
project containing the __init__.py, and the others not containing an 
__init__.py, and the main package doesn't declare a namespace but the 
others do, then that scenario will still work.  If you don't know what this 
means, don't worry about it.  :)

Here's the really goofy part, that you need to deal with if you are 
currently distributing any win32.exe installers for a project that uses 
namespace packages:

If you build a win32.exe with the latest setuptools in SVN, and your users 
use easy_install to install it, they *must* upgrade to the latest 
setuptools as well, or they will get a bunch of stuff about easy_install 
not knowing how to process various files, and the install will fail.  (This 
is because setuptools now includes additional .pth files to munge namespace 
package stuff, and the old .exe-to-.egg conversion doesn't know how to 
handle it.)

So anyway, if you care about this scenario (you distribute bdist_wininst 
win32.exe files but *not* win32.egg files), you should make sure you and 
your users are on the same setuptools version.  But if you provide 
win32.egg files or do *not* provide win32.exe files, everything's cool.