time.clock() should emit a DeprecationWarning

[vstinner]

BPO	31803
Nosy	@malemburg, @freddrake, @abalkin, @vstinner, @benjaminp, @benhoyt, @ethanfurman, @serhiy-storchaka
PRs	bpo-31803: Remove time.clock() #4018 bpo-31803: time.clock() now emits a DeprecationWarning #4020 bpo-31803: time.clock becomes an alias to time.perf_counter #4062

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2017-12-19.00:46:51.284>
created_at = <Date 2017-10-17.13:00:45.598>
labels = ['3.7', 'library']
title = 'time.clock() should emit a DeprecationWarning'
updated_at = <Date 2017-12-19.00:46:51.282>
user = 'https://github.com/vstinner'

bugs.python.org fields:

activity = <Date 2017-12-19.00:46:51.282>
actor = 'vstinner'
assignee = 'none'
closed = True
closed_date = <Date 2017-12-19.00:46:51.284>
closer = 'vstinner'
components = ['Library (Lib)']
creation = <Date 2017-10-17.13:00:45.598>
creator = 'vstinner'
dependencies = []
files = []
hgrepos = []
issue_num = 31803
keywords = ['patch']
message_count = 35.0
messages = ['304502', '304503', '304504', '304505', '304506', '304507', '304508', '304513', '304516', '304536', '304537', '304555', '304556', '304561', '304565', '304567', '304569', '304572', '304664', '304668', '304671', '304746', '304747', '304748', '304749', '304885', '304941', '304948', '304997', '304999', '305004', '305040', '305046', '305088', '308598']
nosy_count = 9.0
nosy_names = ['lemburg', 'fdrake', 'belopolsky', 'vstinner', 'benjamin.peterson', 'mrabarnett', 'benhoyt', 'ethan.furman', 'serhiy.storchaka']
pr_nums = ['4018', '4020', '4062']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = None
url = 'https://bugs.python.org/issue31803'
versions = ['Python 3.7']

[vstinner]

The behaviour of the time.clock() function is not portable: on Windows it mesures wall-clock, whereas it measures CPU time on Unix. Python has time.process_time() and time.perf_counter(), since Python 3.3, which are portable, well defined and have a better resolution.

time.clock() was deprecated in Python 3.3 documentation, but calling time.clock() didn't raise a DeprecationWarning. I proposed to remove it from Python 3.7.

Sometimes, a deprecated function raises a DeprecationWarning in Python version N, before removing it from Python version N. time.clock() doesn't emit such warning, but I consider that it is possible to remove it anyway.

While it can be annoying to have to patch code to no more use time.clock(), I consider that it's worth it for portability and better clock resolution.

Attached PR removes time.clock() and time.get_clock_info() doens't accept 'clock' anymore.

Current time.clock() documentation:
----------------------------
.. function:: clock()

.. index::
single: CPU time
single: processor time
single: benchmarking

On Unix, return the current processor time as a floating point number expressed
in seconds. The precision, and in fact the very definition of the meaning of
"processor time", depends on that of the C function of the same name.

On Windows, this function returns wall-clock seconds elapsed since the first
call to this function, as a floating point number, based on the Win32 function
:c:func:`QueryPerformanceCounter`. The resolution is typically better than one
microsecond.

.. deprecated:: 3.3
The behaviour of this function depends on the platform: use
:func:`perf_counter` or :func:`process_time` instead, depending on your
requirements, to have a well defined behaviour.
----------------------------

[vstinner]

With the PR, Python 3.7 will still requires the C clock() function to build on Unix, since time.process_time() uses it as the last fallback if all other functions failed.

Maybe we can require to have other functions used by time.process_time() (clock_gettime(CLOCK_PROF), getrusage(), times(), ...), but I consider that it can be done later. This change may impact the Python portability: compilation error when building Python, see bpo-22624.

[benhoyt]

I don't think this is a good idea. I still use time.clock() out of habit (on Windows), and from the PR it's clear that the standard library and tests do too. I wouldn't be at all surprised to find others do as well.

I realize it's been deprecated since 3.3, but without a DeprecatingWarning, that's easy to miss. What about adding a DeprecatingWarning for 3.7 and deprecate it later, maybe in 3.9? (I know that's a long time, but time.clock() is an old function so we should be cautious!)

[serhiy-storchaka]

I think it is better to not remove time.clock() until EOL of 2.7. And in any case it first should start emitting a deprecation warning for a one or two releases.

[vstinner]

Ben Hoyt: "... from the PR it's clear that the standard library and tests do too."

I disagree here. The standard library doesn't use time.clock() since Python 3.3. Better clocks like time.perf_counter() or time.monotonic() are now used in the standard library.

My PR onl changes two old tests and the very old turtledemo. I never used turtledemo, I didn't now that it exists neither :-)

"I wouldn't be at all surprised to find others do as well."

Oh, me neither. I'm quite sure that time.clock() is used in the wild. The problem is that you should not use it :-)

"I realize it's been deprecated since 3.3, but without a DeprecatingWarning, that's easy to miss. What about adding a DeprecatingWarning for 3.7 and deprecate it later, maybe in 3.9? (I know that's a long time, but time.clock() is an old function so we should be cautious!)"

I never understood the willingness of DeprecationWarning since almost nobody configures Python to run them. In my experience, even when they are displayed, they are usually ignored until the feature is really removed and then people only really start to look at the issue :-)

But I'm fine with keeping the function and emit a warning in Python 3.7, and remove it from Python 3.8.

[serhiy-storchaka]

A runtime deprecation warning was not emitted in 3.3 because two alternatives, time.process_time() and time.perf_counter(), were not available before 3.3. It would be hard to write a warning-free code that supports 3.3 and earlier versions at the same time. But now 3.2 is virtually out of use and I think we can start emitting a deprecation warning at runtime.

And maybe make 2to3 replacing time.clock() with time.process_time() or time.perf_counter()?

[vstinner]

Serhiy: "I think it is better to not remove time.clock() until EOL of 2.7. And in any case it first should start emitting a deprecation warning for a one or two releases."

I really hate using 2.7 EOL as the final countdown to start changing things. Are we building a new "Python 3" chaos where everything explode at once?

IMHO it's not that hard to write code compatible with Python 2 and Python 3:

try:
from time import perf_counter # Python 3
except ImportError:
from time import clock as perf_counter # Python 2

time.clock() is probably not the only code which requires two code paths in any non trivial application which wants to stay compatible with Python 2.

time.clock() is usually used for benchmarking. I hope that all benchmarking code was already patched to use time.perf_counter() when available, to make the code portable and get better resolution on Unix.

[mrabarnett]

@victor: True, people often ignore DeprecationWarning anyway, but that's their problem, at least you can say "well, you were warned". They might not have read the documentation on it recently because they have not felt the need to read again about a function with which they are already familiar.

[vstinner]

I proposed PR 4020 to emit a DeprecationWarning in time.clock() and time.get_clock_info('clock').

[vstinner]

New changeset 884d13a by Victor Stinner in branch 'master':
time.clock() now emits a DeprecationWarning (GH-4020)
884d13a

[vstinner]

Ok, I modified time.clock() and time.get_clock_info('clock') to emit a DeprecationWarning.

Let's wait for Python 3.8 to remove time.clock() ;-)

Thanks for the reviews Serhiy Storchaka and Diana Clarke!