Monday, March 22

Frameworks, Libraries, Namespaces and Distributions

I've been busy not working on the code for my game engine framework Grease recently. I've actually been working on the documentation, but since I can't help myself, I've been thinking a good bit about the code, and specifically what I want to work on next.

The functionality that I plan to work on next is rather general 2D geometry and vector graphics. The important thing is that although Grease will depend on these things, they are not part of the framework per se. They should be useful for folks who don't buy into Grease's framework dogma, or don't need its features. Simply put they will be libraries that could be perfectly happy outside of Grease or any framework.

So, humble denizens of the Python planet, what is the best approach to naming and packaging these libraries for distribution? I see two possible options, both with pros and cons:
  1. Put them under the grease "brand" packaging them as something like: grease.geometry and They would be distributed separately and probably together with grease the framework as well.
  2. Give them their own independent name (I'm leaning toward flatly) and package them separately from grease, though grease would depend on them.
#1 has some advantages:
    • Less "brand" complexity. It's obvious that is part of the grease project, and when used inside of grease there's one less arbitrary brand-name to remember.
    • It's easy to envision these libraries fitting snugly with the rest of the framework in terms of documentation and what not.
    • It's pretty easy to justify folding the release cycle of the libraries in that of the framework.
    And some disadvantages:
    • The independence of these subpackages is unclear, folks may be reluctant to use them if they feel that they carry too much framework baggage or cognitive complexity.
    • I'm not sure the best way to actually make these separate from a distutils perspective, or whatever distribution flavor of the minute is in fashion. I suspect they should just live in their own directory trees and get stitched into the grease top-level package at installation-time. I'm wary of drawbacks and unintended side-affects of that, however.
    • They're nested rather than flat (sorry Tim).
    #2 also has some advantages:
    • The independence of the library package(s) is obvious.
    •  It's rather obvious how to organize them from a distribution perspective.
    • They aren't weighed down by any framework connotations.
    • The namespace is flatter.
    And of course disadvantages:
    • They don't promote the framework "brand" in any way and may be perceived as less well integrated with the framework.
    • They would feel like more independent creatures to me, thus I think I would tend to fuss about them individually more. That's a subjective thing, of course, and not necessarily bad for users.
    • It's not as clear to me how to deal with them as grease dependencies. Bundle them or fetch them at installation time?
    Honestly I'm able to justify both ways to myself, and of course it's not a matter of life-and-death. But it does feel like an important api decision and I value any opinion or ideas you may have on the matter. So please comment if you feel inclined.

    Also I'm interested in people's opinions on bundling vs. fetching dependencies at installation. In the bad old days, bundling was basically a no-brainer with Python, but given things like setuptools/distribute and buildout, the latter has gained appeal. Which do you prefer?