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

[Phillip J. Eby]

At 04:28 PM 12/13/02 -0500, Jim Fulton wrote:
>Phillip J. Eby wrote:
>..
>
>>from peak.naming import api as naming
>
>And this is good ... why?

1. Everything in the naming API is then only one dot away

2. Access is via a prefix ("naming.") so the top-level namespace in the 
importing module isn't cluttered or conflicting.


>>naming.lookup('something')
>
>Is lookup part of the convention or simply an example function?

Example function, sorry.  I probably should've used "foo" instead of a real 
example.  :)


>>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.
>
>What is the advantage of api over __init__?

Makes it possible for packages which want to reuse part of a package, not 
to require the whole thing to be imported.  This can slash the startup and 
runtimes for small scripts enormously (in proportion to the script's total 
run time).

There are also some advantages to simplifying import order for 
interdependent packages; For example, if you have a package A whose classes 
want to provide an interface from package B, but package B contains things 
that depend on A's classes.  Being able to say:

A:
from B.interfaces import ISomething

B:
from B.somemodule import Something

Without having to sort out a precise ordering in the package __init__ 
modules can be a nice convenience.

Neither of these are killer-strong features.  In *principle*, they aren't 
necessary.  But in practice, they make life a little easier all round.