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

Steven D'Aprano steve at pearwood.info
Fri Apr 6 12:25:20 CEST 2012

Cameron Simpson wrote:
> On 05Apr2012 08:50, Steven D'Aprano <steve at pearwood.info> wrote:
> | Although I don't like the get_clock() API, I don't think this argument against 
> | it is a good one.
> Just to divert briefly; you said in another post you didn't like the API
> and (also/because?) it didn't help discoverability.
> My core objective was to allow users to query for clocks, and ideally
> enumerate and inspect all clocks. Without the caller having platform
> specific knowledge.

Clocks *are* platform specific -- not just in their availability, but also in 
the fine details of their semantics and behaviour. I don't think we can or 
should try to gloss over this. If people are making decisions about timers 
without knowledge of what their platform supports, they're probably making 
poor decisions. Even the venerable time.time() and time.clock() differ between 
Linux and Windows.

> Allowing for the sake of discussion that this is desirable, what would
> you propose as an API instead of get_clock() (and its friend, get_clocks()
> for enumeration, that I should stuff into the code).

The old ways are the best. We don't have math.get_trig() and math.get_trigs() 
functions for querying trigonometric functions, we just expose the functions 

I think the way to enumerate and inspect all clocks is with the tried and true 
Python introspection tools that people use on all other functions:

* use dir(time) to see a list of names available in the module
* use help(time) to read their help
* read the Fine Manual to find out more
* use try... except... to detect the existence of a clock

There's nothing special about clocks that needs anything more than this.

get_clock() looks like a factory function, but it actually isn't. It just 
selects from a small number of pre-existing clocks. We should just expose 
those pre-existing clocks directly. I don't see any advantage in adding that 
extra level of indirection or the addition of all this complexity:

* a function get_clock() to select a clock
* a function get_clocks() to enumerate all the clocks
* another function for querying the properties of a clock

All those functions accomplish is to increase the complexity of the API, the 
documentation and the implementation. It's one more special case for the user 
to learn:

"To find out what functions are available, use dir(module), except for clocks, 
where you have to use time.get_clocks()."


Another problem with get_clock() -- it will be an attractive nuisance for the 
sort of person who cares about symmetry and completeness. You will have a 
steady trickle of "feature requests" from users who are surprised that not 
every combination of features is supported. Out of the eight or sixteen or 
thirty-two potential clocks that get_clock() tempts the user with, only three 
or five will actually exist.

The only advantage of get_clock is that you don't need to know the *name* of a 
platform clock in order to use it, you can describe it with a series of flags 
or enums. But in practice, that's not an advantage, that's actually a 
disadvantage. Consider:

"Which clock should I use for such-and-such a task, foo or bar?"


"Which clock should I use for such-and-such a task, get_clock(spam, eggs, 
cheese) or get_clock(ham, eggs, truffles)?"

The mere mechanics of talking about these clocks will suffer because they 
aren't named.


More information about the Python-Dev mailing list