[Python-ideas] PEP for enum library type?

[Nick Coghlan]

On Thu, Feb 14, 2013 at 9:48 AM, Steven D'Aprano <steve at pearwood.info> wrote:
> 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 at gmail.com   |   Brisbane, Australia