Recently we’ve started adding TiddlyWeb plugins to a virtual namespace.

Holger (of py.test fame) was interested in this technique, so I posted my experience to the py-dev mailing list — which I figured was worth copying here:

The goal is to use a common package name (here: “foo”) for multiple independent modules or packages (“alpha” and “bravo” – to be accessed as foo.alpha and foo.bravo, respectively).

It’s actually rather simple:
The individual components must be contained in a directory named after the virtual namespace, with an __init__.py containing nothing but the following statement:
__import__("pkg_resources").declare_namespace(__name__)
To make Python aware of the local package (e.g. for running tests out of the repository), something like the following is required in a root-level __init__.py:
path = os.path.abspath(VIRTUAL_NAMESPACE)
sys.modules[VIRTUAL_NAMESPACE].__dict__["__path__"].insert(0, path)
This is illustrated here:
http://gist.github.com/231862

Disclaimer: I’m far from being an expert, just sharing what we’ve learned so far (it’s an ongoing effort).

While there are other options, this currently appears to be the most compatible approach (as confirmed by Tarek).

Update: Some further insights made me tweak the approach to module-path mangling.