[Python-Dev] PEP 423 : naming conventions and recipes related to packaging

[Paul Moore]

On 27 June 2012 12:34, Antoine Pitrou <solipsis at pitrou.net> wrote:
> On Wed, 27 Jun 2012 21:19:57 +1000
> Nick Coghlan <ncoghlan at gmail.com> wrote:
>> I thought the PEP actually covered it pretty well:
>> - if you don't want to worry about name conflicts for every module, pick
>> *one* short top level namespace for your group and use that
>> - for shared modules, use the top level namespace with PyPI as the name
>> registry
>
> That's not very clear to me when reading the PEP.
> For example, one of the items in the "overview" is "use top-level
> namespace for ownership". I don't think it should be, unless we want to
> promote such a practice.

I agree. I only skimmed the PEP, but even on a skimming, I got the
impression that it was promoting the use of namespaces for ownership,
in a Java-like way. The part Nick quoted is substantially more
reasonable (assuming that's a direct quote, rather than Nick's
summarisation) but the principle should be made clear right at the
top.

I'd say that a headline item should be something like;

Using namespaces:
 - "Flat is better than nested" - where possible, use a single
top-level name for your package (check on PyPI that the name you
choose isn't in use).
 - Where you expect to have multiple packages all relating to the same
top-level functionality, it may make sense to use a single top-level
namespace package, and put your packages underneath that.
 - There should never be a need to use more than one level of
namespace (if you think there is, you should probably promote each of
the level-2 namespaces.to the top level).
 - Namespaces (and package names) should always be based on
functionality, never on ownership[1].

Personal or private code doesn't need to follow these guidelines, but
be aware that personal code often ends up more widely used than
originally envisaged...

[1] Sorry, Barry. There clearly needs to be an exception for the flufl
namespace :-)

Paul.