On Thu, Feb 14, 2013 at 9:48 AM, Steven D'Aprano
Besides, the presence of a second, non-obvious solution is not a violation of One Obvious Way.
Something that is often forgotten is that having two ways to do something is often *good* for your API design, because it lets you design one simple API that covers a large fraction of use cases, and then a more complex underlying API that covers all (or almost all) of the rest. A procedural wrapper around an object-oriented core is the classic means of achieving this, and the standard library does it all over the place (sometimes we don't publish the OO core, but the option is there if our users demand the extra flexibility). The trick to doing it well is to make sure that users are aware that when the simple API is sufficient, that's the one they should use. Only when that API is inadequate should they reach for the more complex one. It's very, very easy to fall into the trap of documenting the comprehensive core first, and then saying "oh, by the way, here's this convenient helper function that means you will probably never need to worry about all that underlying complexity". The subprocess docs used to fall into that trap: call, check_call and check_output cover many use cases, with Popen as the complex fallback, but the old docs hit readers in the face with Popen, and only mentioned the helper functions as an afterthought. The new docs have the helper functions front and centre, with Popen relegated to "if you really need it" status. The flufl.enum docs *do* currently fall into the trap of treating enum.make as an afterthought rather than as the preferred creation API for the cases that it can handle, though. Armin Ronacher has a lovely elaboration of this principle here: http://lucumr.pocoo.org/2013/2/13/moar-classes/ (although he's mostly complaining about the other direction, simple procedural APIs which *don't* expose a flexible OO core, rather than the one here where an OO core is exposed ). Cheers, Nick. -- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia