Cameron Simpson wrote:
On 05Apr2012 08:50, Steven D'Aprano <steve@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 directly. 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()." Blah. 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?" versus "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. -- Steven