[Python-Dev] an alternative to embedding policy in PEP 418

[Steven D'Aprano]

Lennart Regebro wrote:
> On Tue, Apr 3, 2012 at 08:03, Cameron Simpson <cs at zip.com.au> wrote:
>>  clock = get_clock(MONOTONIC|HIRES) or get_clock(MONOTONIC)
>>
>> If the symbol names are not the horribleness, can you qualify what API
>> you would like more?
> 
> Well, get_clock(monotonic=True, highres=True) would be a vast
> improvement over get_clock(MONOTONIC|HIRES). I also think it should
> raise an error if not found. The clarity and easy of use of the API is
> much more important than how much you can do in one line.

That's a matter of opinion. I'm not particularly fond of this get_clock idea, 
but of the two examples given, I much prefer the first of these:

get_clock(MONOTONIC|HIRES)
get_clock(monotonic=True, highres=True)

and not just because it is shorter. The API is crying out for enum arguments, 
not a series of named flags.

But frankly I think this get_clock API sucks. At some earlier part of this 
thread, somebody listed three or four potential characteristics of clocks. If 
we offer these as parameters to get_clock(), that means there's eight or 
sixteen different clocks that the user can potentially ask for. Do we really 
offer sixteen different clocks? Or even eight? I doubt it -- there's probably 
only two or three. So the majority of potential clocks don't exist.

With get_clock, discoverability is hurt. How does the caller know what clocks 
are available? How can she look for documentation for them?

A simple, obvious, discoverable API is best. If we offer three clocks, we have 
three named functions. If some of these clocks aren't available on some 
platform, and we can't emulate them, then simply don't have that named 
function available on that platform. That's easy to discover: trying to use 
that clock will give a NameError or AttributeError, and the caller can then 
fall back on an alternative, or fail, whichever is appropriate.



-- 
Steven