How to improve the usability of nested packages

Michael Schwarz at
Fri Nov 2 17:11:28 CET 2012

I need some guidance on how to structure a large library with lots of
packages and sub-packages. Using the library should be as effortless
as possible. It's your average beast of a catch-all for sharing code
across applications at our company. Let's call it "the_library". In my
attempt to structure the library, I was following two principles:

- The complete library is contained in a single package. This is to
avoid polluting the top-level namespace.
- Only modules and sub-packages directly under the top-level package
should be imported directly. This means that any class or function in
the library is accessed using the same qualified name everywhere
inside the library or the application. This makes moving code around

Following this, using a module from the library is pretty
straight-forward. A typical file in the application code could start

from the_library import sip, rtp, sdp

This works from any module or script in the library or application.
Then I decided to split the "sip" module into smaller modules, e.g.
"message", "transaction", "dialog", all contained in a package named
"sip". Ideally, an application would still import the sip package
using the import above and then, for example, access the "DialogID"
class using "sip.dialog.DialogID". Currently this is only possible
when also explicitly importing the "dialog" module:

from the_library import sip
import the_library.sip.dialog

This is ugly and seems unnecessary to me as, for example, having all
the modules in the "sip" package available using a single import would
not pollute the local namespace. So I tried to enable this by
importing all the modules in the "sip" package from the package's

from . import message, transaction, dialog

… which doesn't work. Some of the modules reference other modules in
the same package. I'm not talking about cyclic references, but, for
example, the "dialog" module uses the "transaction" module. The
problem is that the "dialog" module uses the same mechanism shown
above to import the other modules from it's package. This means that
modules and packages are imported in this order:

- Application code executes "from the_library import sip"
- the_library/ is executed. No imports here.
- the_library/sip/ executes "from . import [...], dialog"
- the_library/sip/ executes "from the_library import sip"

During the last import a problem arises: The module object for the
package "the_library" does not yet have a "sip" member (as it is still
executing the import) and so the import fails. It is still possible to
import the "transaction" module directly from the "dialog" module

from . import transaction

But this would make the "transaction" module available under a
different qualified name as anywhere else (where it's accessed using

What path would you take to circumvent this problem? Would you break
the rule that any module should be accessed using the same way, no
matter from where it is accessed, or would you maybe structure the
library entirely different?

Thanks for any suggestions!


More information about the Python-list mailing list