Safest and most reliable way to measure short intervals in Python? (cross-platform, cross-hardware, resistant to DST and leap seconds)

The more I read about datetime arithmetic, the bigger a headache I get.

There's lots of different kinds of time:

• Civil time
• UTC
• TAI
• UNIX time
• system time
• thread time
• CPU time

And then the clocks can run faster or slower or jump backwards or forwards because of

• daylight savings
• moving across timezones
• leap seconds
• NTP synchronization
• general relativity

And how these are dealt with depends in turn on:

• Operating system
• Hardware
• Programming language

So please can somebody tell me, for my specific use case, the safest and most reliable way to measure a short interval? Here is what I am doing:

I'm making a game in Python (3.7.x) and I need to keep track of how long it has been since certain events. For example, how long the player has been holding a button, or how long since an enemy has spotted the player, or how long since a level was loaded. Timescales should be accurate to the millisecond (nanoseconds are overkill).

Here are scenarios I want to be sure are averted:

• You play the game late at night. In your timezone, on that night, the clocks go forward an hour at 2am for DST, so the minutes go: 1:58, 1:59, 2:00, 3:01, 3:02. Every time-related variable in the game suddenly has an extra hour added to it -- it thinks you'd been holding down that button for an hour and 2 seconds instead of just 2 seconds. Catastrophe ensues.

• The same, but the IERS decides to insert or subtract a leap second sometime that day. You play through the transition, and all time variables get an extra second added or subtracted. Catastrophe ensues.

• You play the game on a train or plane and catastrophe ensues when you cross a timezone boundary and/or the International Date Line.

• The game works correctly in the above scenarios on some hardware and operating systems, but not others. I.e. it breaks on Linux but not Window, or vice versa.

And I can't really write tests for these since the problematic events come around so rarely. I need to get it right the first time. So, what time-related function do I need to use? I know there's plain old time.time(), but also a bewildering array of other options like

• time.clock()
• time.perf_counter()
• time.process_time()
• time.monotonic()
• and then nanosecond variants of all of the above.

From reading the documentation it seems like time.monotonic() is the one I want. But if reading about all the details of timekeeping has taught me anything, it's that these things are never quite what they seem. Once upon a time, I thought I knew what a "second" was. Now I'm not so sure.

So, how do I make sure my game clocks work properly?

The specification of time module is the best place to look for details about each of those.

There, you can easily see that:

• time.clock() is deprecated and should be replaced with other functions
• time.process_time() counts only CPU time spent by your process, so it is not suitable for measuring wall clock time (which is what you need)
• time.perf_counter() has the same problem as time.process_time()
• time.time() is just about right, but it will give bad timings if user modifies the current time
• time.monotonic() - this seems to be the safest bet for measuring time intervals - note that this does not give you current time at all, but it gives you a correct difference between two time points

As for the nanoseconds versions, you should use those only if you need nanoseconds.