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

Cameron Simpson cs at zip.com.au
Wed Apr 4 02:52:08 CEST 2012

On 04Apr2012 09:53, Steven D'Aprano <steve at pearwood.info> wrote:
| 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).[...]
| 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.

Enums would be ok with me. I went with a bitmask because it is natural
to me and very simple. But anything symbolicly expression will do.

| 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.

That's not the point. I think we should offer all the platform system clocks,
suitably described. That there are up to 8 or 16 flag combinations is
irrelevant; no user is going to try them all. A user will have requirements
for their clock. They ask for them either blandly via get_clock() or (for
example considering monotonic most important) via monotonic_clock(). In the
latter case, the supported clocks can be considered in a more apt order via a
different internal clock list.

| With get_clock, discoverability is hurt.

No, because the other calls still exist. (In my proposal. I see Victor's
characterised this as either/or in the PEP, never my intent.)

| How does the caller know what clocks 
| are available?

I would definitely want either:

  - the module clock lists available via public names, for example as in
    my sample clockutils.py code (ALL_CLOCKS, MONTONIC_CLOCKS etc) or
    via some map (eg clocks['monotonic']).

  - a get_clocks() function to return matching clocks, like get_clock()
    but not stopping on the first match

  - an all_clocks=False parameter to get_clock() to get an iterable of
    the suitable clocks

| How can she look for documentation for them?

There is good text in the PEP. That could be easily moved into the
module doco in a "clocks" section. Since my clocks proposal wraps clocks
in an object, they _can_ have nice class names and good docstrings and
more metadata in the object (possibilities including .epoch, .precision,
.is_steady() methods, .os_clock_name (eg "QueryPerformanceCounter"), etc).

| 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.

And I hate this. Because many platforms offer several OS clocks. The
time module SHOULD NOT dictate what clocks you get to play with, and you
should not need to have platform specific knowledge to look for a clock
with your desired characteristics.

If you just want montonic() and trust the module authors' policy
decisions you can go with monotonic(), have it do AttributeError if
unavailable and never worry about discoverability or the inspectable
object layer. Many will probaby be happy with that.

But without get_clock() or something like it, there is no
discoverability and not ability for a user to decide their own clock
choice policy.
Cameron Simpson <cs at zip.com.au> DoD#743

Your modesty is typically human, so I will overlook it. - a Klingon

More information about the Python-Dev mailing list