[Python-Dev] Package Style Guide

[Andy Robinson]

Thanks for all the replies.  We really need a 'style guide'
on package use, so I hope this example can be thrashed
out and used to help others.  We need to decide something
and release next week, and also provide good docs for
other users who will be new to Python.

Apart from the ambiguity, which was a surprise but which 
we can work around, I have some general questions on the
"right thing".  Here are my examples:

1. use of __init__ to save users work
------------------------------------ 
ReportLab has a subpackage called 'platypus' which we have
just reorganized and not yet released.  The division
into subpackages is clear - each exposes a different
kind of functionality - but the division of each
package into modules is based on keeping a sane 
length for each and not on providing a friendly
user interface.

reportlab
    pdfgen
        canvas.py  defines class Canvas
        textobject.py defines class TextObject
        pathobject.py defines class PathObject
    platypus
        (the same problem, but 3x worse)
    lib
        (loads of modules, all independent)

We reached a point where users need to import eight or 
ten classes to do useful work and were having to put eight 
or ten different import lines at the top of every script.  
This just feels dumb and wrong.

So, the 'least messy' idea was to put __init__.py
methods in each subpackage which explicitly import
what they need.  (We have not used "import *")

---reportlab/pdfgen/__init__.py--------
from canvas import Canvas
from textobject.py import TextObject
from pathobject.py impory PathObject

Then users can just do:
from reportlab.pdfgen import Canvas, PathObject, TextObject

It seems that this (a) makes life easier for users, and
(b) gives us freedom to refactor code as it grows, without
changing the user interface.  

Is this style evil?  If so, why? 


2. Ambiguities running scripts within package
---------------------------------------------
We have various test functions scattered 
throughout our distribution.  A control script iterates
through the lot and kicks them off before every release,
executing everything with an 'if __name__=='__main__'
handler.  If these were standalone scripts just for 
testing, they could import "reportlab.platypus.tables"
or whatever.  But if I just want to put a test
routine at the end of "reportlab.platypus.tables"
then I seem destined to run into exactly the ambiguity
outlined before.  

Should test scripts all be moved out of the package?  
Indeed, is Python behaving the way it ought to?

3. Preferred subpackage import technique
----------------------------------------
I have two scripts 'spam.py' and 'eggs.py' in
subpackage 'A.B'.  spam imports eggs.
Should it say...
   import eggs
or...
   import A.B.eggs?

Both work sometimes, but can lead to different
behavious sometimes.  Which is the preferred style?

Thanks,

Andy Robinson