[Zope3-dev] packaging conventions note

[Phillip J. Eby]

At 11:16 AM 12/6/02 -0500, Barry A. Warsaw wrote:

> >>>>> "SH" == Shane Hathaway <shane@zope.com> writes:
>
>     SH> The downside is that then it's harder to find classes whose
>     SH> name you know but not their module.  I don't like the idea of
>     SH> requiring module names to be short and lowercase.  I do like
>     SH> the idea of package names being short and lowercase, OTOH.
>
>     SH> Java's convention of naming the module the same as the class
>     SH> is a big advantage for navigating lots of code.  You rarely
>     SH> have to guess where a class is located.  (Just look at
>     SH> Twisted.  If you want to find the "TwistedSocketNotifier"
>     SH> class, would you know to look in "qternet.py" without using
>     SH> grep?)
>
>I'm with you Shane, for exactly that reason.  I've used module-name-
>is-class-name convention for both the email package and Mailman and I
>really like it.  I'm also with you on the short, lowercase package
>name (although Mailman doesn't use this mostly for historical
>reasons).
>
>As for centralized documentation about how all the classes fit
>together, well, that can /still/ go in __init__.py if you want, or it
>can just go in some .tex or .txt file.

Here's a question: are you concerned about finding the class to *edit*, or 
to *use*?  Because if it's to *use* the module, then an "api" or "public" 
thing works great.  Everything's always available from that module.

If it's to *edit*, then just use the convention that the "api" or "public" 
module imports items from the other modules by name, e.g.:

from package.foo import ThisFooThing, ThingWithoutFooInItsName
from package.bar import Table, Drink
...

Now, if you want to know where the class is, just look at the API module.

In practice, for my code I don't bother with this latter convention; 
instead I put an __all__ in each module that lists what it will export to 
the API module, which uses import *.