As far as the import system goes, Barry Warsaw added a really nice page to the language reference[1].  However, it sounds like your concern is with taking advantage of the tools that importlib provides.

First of all, a good thing to recognize is that importlib Python 3.3 exposes a much richer public API, including exposing the "default" import machinery.  While importlib.abc is meaningful, importlib.machinery is more useful in your case.  In versions prior to 3.3, things aren't as easy.

In other Python 3 versions one approach you could take is to **carefully** use the private importlib APIs to get what you want.  If you do that, I'd recommend that your code target the public 3.3 APIs and then write a wrapper around the earlier private APIs to get them to be compatible.  There really shouldn't be a lot of difference.  The key is to target Python 3.3's importlib.

For Python 2, I'd still recommend targeting 3.3's importlib API and writing wrappers to make that work.  This would likely involve more effort to backport whole chunks of the 3.3 importlib implementation.  Better to simply port your code to Python 3.  :)

Secondly, the import system is a complex piece of machinery.  The new reference that Barry did helps pull it all together, but there are simply a lot of moving parts in various layers.  Adding examples for the importlib API may help for working with that API, but any activities in hooking into the import system should be done with a firm understanding of how it works since it's easy to break things.  Currently there isn't any easy way around that and I doubt any of that will change for a long time (due to the effort required).

Lastly, take a look at pylt[2].  It's a project I'm working on for source-to-source translation that hooks into the import system.  Though it isn't finished yet, the import side of things is mostly done.  Hopefully I'll have all the tests done in the next few days.

For pylt I've made use of the 3.3 importlib API along with a couple of things that we should see in 3.4 that I've "backported" [3].  The code there should give you an idea of how I've done essentially what you are looking to do.

Ultimately, any recommendations you can give on making the import system more approachable would be awesome.  Though it will take a lot of thought, discussion, and effort to make the import system "easy", there is still a lot of room for improvement in making it understandable.  Your perspective would be meaningful in working toward a sensible improvement.


[1] http://docs.python.org/dev/reference/import.html
[2] https://bitbucket.org/ericsnowcurrently/pylt/
[3] http://bugs.python.org/issue15627