[Zope3-dev] Packaging conventions (was Re: PyCon DC 2003: Call For Papers)

[Phillip J. Eby]

Wow, you guys just independently re-invented practically the same set of 
conventions Ty and I worked out for PEAK...  which was done independently 
of Twisted...  which means that these may be some sort of "natural order of 
things" for large Python packages.  :)

The only addition to this that we do in PEAK, is that there *is* an "api" 
module in major packages, but it imports selected classes and functions 
from the rest of the package.  It's designed to be used like this:

from peak.naming import api as naming

naming.lookup('something')

That is, for "shortcut" access to commonly used features of the package, 
those intended to be used by an app developer as opposed to a framework 
extender.  In PEAK, usually the "api" package consists of a series of "from 
foo import *" statements importing all the exported capabilities of various 
nearby modules that expose API-ish things, and always including the 
"interfaces" module, so that a package's interfaces are always available 
via the "api" shortcut.


At 08:41 AM 12/5/02 -0500, Guido van Rossum wrote:

>- Module and package names should be short and lowercase.  Motivation:
>   you'll never again confuse a class with its module.
>
>- Modules should contain more than one class (a rule designed to be
>   broken :-).  Motivation: this way the presentation order of classes
>   (whether top-down or bottom-up) can help the reader to understand
>   what's important; and it clarifies what classes (or functions) are
>   related.  Compare to trying to find where to start in a directory
>   full of classes, listed alphabetically.
>
>- Special case: all interfaces go in "interfaces.py".  Motivation: see
>   previous bullet.  (We tried thinking of a shorter name, but rejected
>   abbrevs and "api.py" is wrong, since quite often several interfaceds
>   are more internal than part of the API.  Also it's still an abbrev,
>   even if a very common one.)
>
>- Since the above rules greatly reduce the number of files, there's
>   much less need to create subdirectories for certain classes of
>   files.  In particular, it seems that views can happily live in the
>   main package directory, rather than in a subdirectory named by
>   category (e.g. "browser").  (Note that we already decided not to
>   group all views in a "views" subdirectory.)  I imagine that if a
>   product has a large number of e.g. images or ZPT templates, they
>   could still go into a separate subdirectory, at the product
>   designer's discretion, but if you have just a few, that's not
>   required.  I found that having only one configure.zcml for a project
>   rather than a main one and one for "browser" related configuration
>   reduces the amount of configuration boilerplate (there's enough of
>   that already :-).