I can sum this report up most simply by quoting the message below:

http://mail.python.org/pipermail/python-list/2001-October/107699.html

Note that this message was posted 5 1/2 years ago (by myself, as it happens), had no follow up, and the problem referred to remains current!  (The chapter on "import" is now section 6.12: nothing else has changed.)

The comment below that "presum[ably] nothing significant has changed" seems less than probable now!

I was looking to understand modules and packages a bit better: they don't behave like proper first class objects (is module.sub_module an attribute?  not really), and so the lack of definitive documentation in this area is sad, particularly after such a long time.


Body of original message follows


Package support in Python 2

Michael Abbott michael at rcp.co.uk
Wed Oct 3 10:58:08 CEST 2001


Is there up to date documentation for package support in Python 2?

Section 6.11 of the "Python Reference Manual" has the following nice quote:


[XXX Can't be bothered to spell this out right now; see the URL http://www.python.org/doc/essays/packages.html for more details, also about how the module search works from inside a package.] 


and the referred URL documents Python 1.5.  I presume that nothing significant has changed recently, but it's certainly disconcerting for something as fundamental as module importing to not actually be part of the core language documentation!

You are certainly right that this should be documented properly.

BTW, after you import x.y, y is an attribute of module x. When you write "x.y.foo", Python knows nothing about modules any more, it just handles attribute access of arbitrary objects which happen to be modules.

Hi Michael, would you be interested in working on a docs patch for this?

Hi Collin,

Well, that's not a terrible idea.  I'll take a look and follow up later.

Any progress on this?

This has now been done by Brett while he wrote the docs for importlib.