Add somes docs for the __main__.__requires__ interface, and also modernise the intro section of the pkg_resources docs.
My thoughts are roughly the same as Jason's: additions look good, not so sure about the change/removal, but I'm more -0 or -0.5; i.e., I wouldn't fight terribly hard to keep the existing text, as I kind of get that you're going for making pkg_resources less about eggs per se and more about distributions. I like that idea, I'm just not sure if this is the right way to do it... but still, I don't feel strongly either way, which is why I've been putting off commenting. ;-)
I do like the additions, though!
While pkg_resources uses eggs, it seemed misleading to me to lead
with that information - to me, eggs feel more like an implementation
detail that the module need defined in order to provide the
capabilities it does. I consider documentation to be in some ways a
sales pitch to potential users, and from that perspective, what the
module can do for them is what matters, rather than how it actually
The only sentence I thought was actually wrong though was "Because
these are new concepts in Python (and not that well established in
other languages either),", though. setuptools celebrates its 10th
birthday next year, and features it pioneered are driving large
portions of the next generation metadata design :)
Once I took that sentence out, though, the rest of the lead in section
didn't work right, so I ended up just deleting most of it. I think
you're right, though - it would be better to keep at least the parts
that talked about what the module does.
I updated the patch to add back a modernised version of the text I removed. It emphasises the fact that eggs aren't just a distribution format, but also an installation format, and that's what powers the support for selective activation of conflicting versions based on sys.path manipulation.
Jason R. Coombs
Yep, awesome: now the intro is improved, not just nuked. ;-) Thanks!