Eric: Yeah I've seen that, it's the one thing that I kept open as I was turning back and forth through the various parts of importlib. So yeah I like that document certainly at least a bit :). Also thanks to both you and Brett for linking that issue, that's certainly something I'll keep an eye on.

Just to repeat the specific things that perhaps we could work on -- I strongly agree that the top of importlib's docs would benefit from reworking the See Also at the top. Also, perhaps that monumental undertaking would be a thing that could be wrangled :P -- like you said, import hooks seem to have two broad use cases: changing *where* a module comes from away from a simple file containing Python source code on a filesystem, and secondly changing what happens when a module is being imported. So I guess what I would love to have would be an example for each of those. An example of a Loader that loaded from somewhere else other than a file, and an example of an Importer that did something else when executing. I'm sure you'll correct me if I've missed an important one. If that's reasonable sounding and I manage to succeed in my own use case, perhaps I'll take a shot at that.

One thing I certainly understand here is that usually I (we) wouldn't have this problem since blog posts and other third party documentation and code can provide examples that are helpful enough to help developers get a sense of what they need to write. The thing for me here was that I didn't really find anything helpful in that sector. importlib is new obviously, so maybe what's given me trouble will be mitigated after 3.3 gets released and a few people write up some examples on their own.

I recognize that there was a huge undertaking here, and that it's still being honed, I hope in no way did this sound disparaging :). Also I hope it didn't sound like a misplaced StackOverflow post -- although certainly the confirmation that I was on the right track should help me finish this off quite easily, so thanks for that as well :).