python project layout

[Peter Hansen]

Huron wrote:
> Hi Peter,
> Thanks for you detailed reply.
> The layout that you suggest sounds wise to me (I'm about to start a
> project).

I wouldn't necessarily recommend something so complex (not that it's 
particular complex, but it's more than just "flat") for a newcomer, 
however.  One of the few small issues you have to deal with in order to 
get such a layout working properly is the "python path" issue, and how 
to import modules that are in another folder.

Normally (aside from the standard library and extensions) only the 
current directory is in sys.path.  Any subfolders that contain 
__init__.py modules are "packages" and you can import from them using 
the "dotted" notation (e.g. "import mypkg.mymodule" will try to load a 
file from ./mypkg/mymodule.py if there is also a ./mypkg/__init__.py 
(even if that file is empty!)).

To import a module in the *parent* directory, however, is another story 
entirely.  You need to get it added to the sys.path, and that's one of 
the things done (dynamically) by our test utilities, so we can be in the 
tests subfolder and type "story015.py" and have it load modules in the 
parent folder.

So in short, start simple and let your layout evolve as you need it to. 
  Don't try to start with a more complex layout than you need or know 
how to handle.  And if you're using a revision control system like 
Subversion (and you better be using something! :-) ) then it's an easy 
matter to rename or move folders at a later time, without losing your 
revision history.

-Peter