[Distutils] namespace_packages: include itself ot not include

[P.J. Eby]

At 12:06 AM 2/8/2011 +0300, Roman Kurakin wrote:
>but one is initial provider of 'aaa' share
>and other consumer of 'aaa' share.

This statement is why you're confused.  A namespace is not "provided" 
by anyone, only participated in.

Think of it this way.  You and I decide to have lunch together.  I am 
not providing the lunch.  You are not providing the lunch.  But we 
are both participating in the lunch.

That is how namespace packages work.  aaa.bbb participates in the aaa 
namespace, therefore it lists aaa as a namespace package.

Better, a concrete example.  zope.interface participates in the zope 
namespace package, so it lists 'zope' in namespace_packages.  There 
is no "zope" package that stands by itself, there are only zope.* 
packages that together participate in the zope namespace.

>Why 'aaa.bbb' should even know that there is, or
>will be any other, for example 'aaa.bbb.ccc'?

It would only do this if you indeed planned to have that happen.

For example, I have a 'peak.util' namespace package.  There are many 
projects, such as DecoratorTools, Importing, and so forth on PyPI 
that provide modules in that namespace.  DecoratorTools is 
peak.util.decorators, Importing is peak.util.imports, and so on.

There is NO peak.util package, however.  You cannot download 
peak.util someplace, because it is a *namespace* package.

The entire point of a namespace package is that it's just a name, and 
NOT an actual package.  You would never import anything directly from 
peak.util, because it's just a place where other packages live.

"peak" is also a namespace package, and there are other projects that 
contribute modules and subpackages to that namespace.


>In a simple case 'shared' is a little bit confusing in case we are 'extending'
>namespace via strict hierarchy aaa.bbb, aaa.ccc, aaa.bbb.ddd etc. Where
>any of packages are initial providers of their own namespaces. 'aaa' and
>'aaa.bbb' share 'aaa' namespace, but one is initial provider of 'aaa' share
>and other consumer of 'aaa' share.

Namespace packages don't work like that.  All participants in a 
namespace are *equal peers*, not "base plus extensions".

Sure, you can DO it, but the tools don't have any notion that one 
package is the base and another is the extender.  That's why you're 
getting confused: you are thinking "base and extension", but 
namespace packages are peer-to-peer.  You participate in a namespace 
by having some code that goes in it, and EVERY project that 
participates in that namespace must declare it -- no exceptions.

(If a project doesn't declare the namespace, and it ends up first on 
sys.path, it will block access to all the other participants in the 
same namespace.)