Pull requests

#14 Merged
Repository
ncoghlan ncoghlan
Branch
docs_update_for_requires
Repository
pypa pypa
Branch
default

Document __main__.__requires__

Author
  1. Nick Coghlan
Reviewers
Description

Add somes docs for the __main__.__requires__ interface, and also modernise the intro section of the pkg_resources docs.

Comments (5)

  1. pje

    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!

    1. Nick Coghlan author

      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 does it.

      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.

  2. Nick Coghlan author

    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.