Back when Eric, Jason, and I sprinted on the PEP 420 implementation, I threatened to actually document how the import machinery worked, updating and reorganizing to include the new PEP 420 protocols. Issue 15295 tracks this: http://bugs.python.org/issue15295 I now have a first draft of the new import machinery documentation. This refactors the import statement docs, moving everything concerning the finding and loading of modules into a separate language reference section. The import statement section then only describes the name binding operations that occur after the module has been loaded. I've also added a bunch of new glossary terms, and updated documentation and code related to the importlib ABCs. Everything lives in the features/pep-420 clone, in the importdocs branch: http://hg.python.org/features/pep-420/shortlog/e6e77d8bb729 I really don't want to extract a patch for the tracker issue, since that will be much less convenient to update with the inevitable deluge of corrections I'm sure I'll get <wink>. Please do review the updated documentation, and send comments either here or in the tracker issue. Given Python's release schedule and my own summer schedule, review is fairly urgent. OTOH, this is just documentation, so if Georg agrees, and the changes look mostly sane, then I can commit it and we can fix up the nits later. Either way, I'd like to commit the docs by mid-next week at the latest (so after rc1 unfortunately). Cheers, -Barry