Imports (in Py3), please help a novice

[John Ladasky]

I'm currently running Python 3.3 on Ubuntu 13.04.

Up until now, I have gotten away with writing modules whose namespace is completely defined within a single Python script.  That has allowed me to use the following, simple setup script for installation by distutils:

## setup.py ##

from distutils.core import setup
setup(name = "foo", version = "1.0", author = "John", py_modules = ["foo"])

##

As long as all the names I want to import are defined in foo.py, which is located in the same folder as my setup.py, this works.  I can execute "import foo" from any Python3 program, and I get my names.

But now this approach is frustrating me.  I'm looking at a 1000-line foo.py file, with five different functions I would like to make importable, and several functions which I do not need to import.  Keeping track of the import statements from other modules which various parts of foo.py uses is getting confusing.  I would like to make things more modular, to simplify my editing.

I don't necessarily need to break it down all the way to a single class per file, but I would like to get closer to that goal than what I have.  I also haven't reached the point where I would need subpackages within my parent package.  Files in a flat folder will do.  And it would be nice that, once those files are copied to site-packages, they would appear in a single sub-folder thereof.

I've just spent the past few hours trying to read the distutils documentation (which is opaque, and has not been revised for Py3, even though I can see articles on-line which indicate that several PEPs concerning imports have been implemented), looking at some existing packages (numpy and wx, both perhaps too complex), and performing some experiments with __init__.py scripts.

I have some __init__.py scripts which can import names when they are executed from within their own directory, but which fail when they are called by another program outside of that directory, indicating that I do not understand how to control the scope.  I've tried to make use of __all__, but apparently that only affects statements of the "from foo import *" variety?  I've installed things with distutils which work -- but which somehow install my modules twice, once in my site-packages folder and then also in a sub-folder of site-packages, creating clutter (which I then delete).  I've tried looking at sys.modules, and I have found that imports will sometimes work even when modules are not listed there.

In short, I'm getting myself lost.

Is there an import / distutils tutorial out there?  I'm looking for it, but perhaps one of you already knows where to find it.  Thanks!