CINXE.COM

<!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <meta name="color-scheme" content="light dark"> <title>PEP 564 – Add new time functions with nanosecond resolution | peps.python.org</title> <link rel="shortcut icon" href="../_static/py.png"> <link rel="canonical" href="https://peps.python.org/pep-0564/"> <link rel="stylesheet" href="../_static/style.css" type="text/css"> <link rel="stylesheet" href="../_static/mq.css" type="text/css"> <link rel="stylesheet" href="../_static/pygments.css" type="text/css" media="(prefers-color-scheme: light)" id="pyg-light"> <link rel="stylesheet" href="../_static/pygments_dark.css" type="text/css" media="(prefers-color-scheme: dark)" id="pyg-dark"> <link rel="alternate" type="application/rss+xml" title="Latest PEPs" href="https://peps.python.org/peps.rss"> <meta property="og:title" content='PEP 564 – Add new time functions with nanosecond resolution | peps.python.org'> <meta property="og:description" content="Add six new “nanosecond” variants of existing functions to the time module: clock_gettime_ns(), clock_settime_ns(), monotonic_ns(), perf_counter_ns(), process_time_ns() and time_ns(). While similar to the existing functions without the _ns suffix, they..."> <meta property="og:type" content="website"> <meta property="og:url" content="https://peps.python.org/pep-0564/"> <meta property="og:site_name" content="Python Enhancement Proposals (PEPs)"> <meta property="og:image" content="https://peps.python.org/_static/og-image.png"> <meta property="og:image:alt" content="Python PEPs"> <meta property="og:image:width" content="200"> <meta property="og:image:height" content="200"> <meta name="description" content="Add six new “nanosecond” variants of existing functions to the time module: clock_gettime_ns(), clock_settime_ns(), monotonic_ns(), perf_counter_ns(), process_time_ns() and time_ns(). While similar to the existing functions without the _ns suffix, they..."> <meta name="theme-color" content="#3776ab"> </head> <body> <svg xmlns="http://www.w3.org/2000/svg" style="display: none;"> <symbol id="svg-sun-half" viewBox="0 0 24 24" pointer-events="all"> <title>Following system colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <circle cx="12" cy="12" r="9"></circle> <path d="M12 3v18m0-12l4.65-4.65M12 14.3l7.37-7.37M12 19.6l8.85-8.85"></path> </svg> </symbol> <symbol id="svg-moon" viewBox="0 0 24 24" pointer-events="all"> <title>Selected dark colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <path stroke="none" d="M0 0h24v24H0z" fill="none"></path> <path d="M12 3c.132 0 .263 0 .393 0a7.5 7.5 0 0 0 7.92 12.446a9 9 0 1 1 -8.313 -12.454z"></path> </svg> </symbol> <symbol id="svg-sun" viewBox="0 0 24 24" pointer-events="all"> <title>Selected light colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <circle cx="12" cy="12" r="5"></circle> <line x1="12" y1="1" x2="12" y2="3"></line> <line x1="12" y1="21" x2="12" y2="23"></line> <line x1="4.22" y1="4.22" x2="5.64" y2="5.64"></line> <line x1="18.36" y1="18.36" x2="19.78" y2="19.78"></line> <line x1="1" y1="12" x2="3" y2="12"></line> <line x1="21" y1="12" x2="23" y2="12"></line> <line x1="4.22" y1="19.78" x2="5.64" y2="18.36"></line> <line x1="18.36" y1="5.64" x2="19.78" y2="4.22"></line> </svg> </symbol> </svg> <script> document.documentElement.dataset.colour_scheme = localStorage.getItem("colour_scheme") || "auto" </script> <section id="pep-page-section"> <header> <h1>Python Enhancement Proposals</h1> <ul class="breadcrumbs"> <li><a href="https://www.python.org/" title="The Python Programming Language">Python</a> » </li> <li><a href="../pep-0000/">PEP Index</a> » </li> <li>PEP 564</li> </ul> <button id="colour-scheme-cycler" onClick="setColourScheme(nextColourScheme())"> <svg aria-hidden="true" class="colour-scheme-icon-when-auto"><use href="#svg-sun-half"></use></svg> <svg aria-hidden="true" class="colour-scheme-icon-when-dark"><use href="#svg-moon"></use></svg> <svg aria-hidden="true" class="colour-scheme-icon-when-light"><use href="#svg-sun"></use></svg> Toggle light / dark / auto colour theme </button> </header> <article> <section id="pep-content"> <h1 class="page-title">PEP 564 – Add new time functions with nanosecond resolution</h1> <dl class="rfc2822 field-list simple"> <dt class="field-odd">Author:</dt> <dd class="field-odd">Victor Stinner <vstinner at python.org></dd> <dt class="field-even">Status:</dt> <dd class="field-even"><abbr title="Accepted and implementation complete, or no longer active">Final</abbr></dd> <dt class="field-odd">Type:</dt> <dd class="field-odd"><abbr title="Normative PEP with a new feature for Python, implementation change for CPython or interoperability standard for the ecosystem">Standards Track</abbr></dd> <dt class="field-even">Created:</dt> <dd class="field-even">16-Oct-2017</dd> <dt class="field-odd">Python-Version:</dt> <dd class="field-odd">3.7</dd> <dt class="field-even">Resolution:</dt> <dd class="field-even"><a class="reference external" href="https://mail.python.org/pipermail/python-dev/2017-October/150046.html">Python-Dev message</a></dd> </dl> <hr class="docutils" /> <section id="contents"> <details><summary>Table of Contents</summary><ul class="simple"> <li><a class="reference internal" href="#abstract">Abstract</a></li> <li><a class="reference internal" href="#rationale">Rationale</a><ul> <li><a class="reference internal" href="#float-type-limited-to-104-days">Float type limited to 104 days</a></li> <li><a class="reference internal" href="#previous-rejected-pep">Previous rejected PEP</a></li> <li><a class="reference internal" href="#issues-caused-by-precision-loss">Issues caused by precision loss</a><ul> <li><a class="reference internal" href="#example-1-measure-time-delta-in-long-running-process">Example 1: measure time delta in long-running process</a></li> <li><a class="reference internal" href="#example-2-compare-times-with-different-resolution">Example 2: compare times with different resolution</a></li> </ul> </li> <li><a class="reference internal" href="#cpython-enhancements-of-the-last-5-years">CPython enhancements of the last 5 years</a></li> <li><a class="reference internal" href="#existing-python-apis-using-nanoseconds-as-int">Existing Python APIs using nanoseconds as int</a></li> </ul> </li> <li><a class="reference internal" href="#changes">Changes</a><ul> <li><a class="reference internal" href="#new-functions">New functions</a></li> <li><a class="reference internal" href="#unchanged-functions">Unchanged functions</a></li> </ul> </li> <li><a class="reference internal" href="#alternatives-and-discussion">Alternatives and discussion</a><ul> <li><a class="reference internal" href="#sub-nanosecond-resolution">Sub-nanosecond resolution</a></li> <li><a class="reference internal" href="#modifying-time-time-result-type">Modifying time.time() result type</a></li> <li><a class="reference internal" href="#different-types">Different types</a></li> <li><a class="reference internal" href="#different-api">Different API</a></li> <li><a class="reference internal" href="#a-new-module">A new module</a></li> </ul> </li> <li><a class="reference internal" href="#annex-clocks-resolution-in-python">Annex: Clocks Resolution in Python</a><ul> <li><a class="reference internal" href="#script">Script</a></li> <li><a class="reference internal" href="#linux">Linux</a></li> <li><a class="reference internal" href="#windows">Windows</a></li> <li><a class="reference internal" href="#analysis">Analysis</a></li> </ul> </li> <li><a class="reference internal" href="#links">Links</a></li> <li><a class="reference internal" href="#copyright">Copyright</a></li> </ul> </details></section> <section id="abstract"> <h2><a class="toc-backref" href="#abstract" role="doc-backlink">Abstract</a></h2> Add six new “nanosecond” variants of existing functions to the <code class="docutils literal notranslate">time</code> module: <code class="docutils literal notranslate">clock_gettime_ns()</code>, <code class="docutils literal notranslate">clock_settime_ns()</code>, <code class="docutils literal notranslate">monotonic_ns()</code>, <code class="docutils literal notranslate">perf_counter_ns()</code>, <code class="docutils literal notranslate">process_time_ns()</code> and <code class="docutils literal notranslate">time_ns()</code>. While similar to the existing functions without the <code class="docutils literal notranslate">_ns</code> suffix, they provide nanosecond resolution: they return a number of nanoseconds as a Python <code class="docutils literal notranslate">int</code>. The <code class="docutils literal notranslate">time.time_ns()</code> resolution is 3 times better than the <code class="docutils literal notranslate">time.time()</code> resolution on Linux and Windows. </section> <section id="rationale"> <h2><a class="toc-backref" href="#rationale" role="doc-backlink">Rationale</a></h2> <section id="float-type-limited-to-104-days"> <h3><a class="toc-backref" href="#float-type-limited-to-104-days" role="doc-backlink">Float type limited to 104 days</a></h3> The clocks resolution of desktop and laptop computers is getting closer to nanosecond resolution. More and more clocks have a frequency in MHz, up to GHz for the CPU TSC clock. The Python <code class="docutils literal notranslate">time.time()</code> function returns the current time as a floating-point number which is usually a 64-bit binary floating-point number (in the IEEE 754 format). The problem is that the <code class="docutils literal notranslate">float</code> type starts to lose nanoseconds after 104 days. Converting from nanoseconds (<code class="docutils literal notranslate">int</code>) to seconds (<code class="docutils literal notranslate">float</code>) and then back to nanoseconds (<code class="docutils literal notranslate">int</code>) to check if conversions lose precision: <div class="highlight-default notranslate"><div class="highlight"><pre># no precision loss >>> x = 2 ** 52 + 1; int(float(x * 1e-9) * 1e9) - x 0 # precision loss! (1 nanosecond) >>> x = 2 ** 53 + 1; int(float(x * 1e-9) * 1e9) - x -1 >>> print(datetime.timedelta(seconds=2 ** 53 / 1e9)) 104 days, 5:59:59.254741 </pre></div> </div> <code class="docutils literal notranslate">time.time()</code> returns seconds elapsed since the UNIX epoch: January 1st, 1970. This function hasn’t had nanosecond precision since May 1970 (47 years ago): <div class="highlight-default notranslate"><div class="highlight"><pre>>>> import datetime >>> unix_epoch = datetime.datetime(1970, 1, 1) >>> print(unix_epoch + datetime.timedelta(seconds=2**53 / 1e9)) 1970-04-15 05:59:59.254741 </pre></div> </div> </section> <section id="previous-rejected-pep"> <h3><a class="toc-backref" href="#previous-rejected-pep" role="doc-backlink">Previous rejected PEP</a></h3> Five years ago, the <a class="pep reference internal" href="../pep-0410/" title="PEP 410 – Use decimal.Decimal type for timestamps">PEP 410</a> proposed a large and complex change in all Python functions returning time to support nanosecond resolution using the <code class="docutils literal notranslate">decimal.Decimal</code> type. The PEP was rejected for different reasons: <ul class="simple"> <li>The idea of adding a new optional parameter to change the result type was rejected. It’s an uncommon (and bad?) programming practice in Python.</li> <li>It was not clear if hardware clocks really had a resolution of 1 nanosecond, or if that made sense at the Python level.</li> <li>The <code class="docutils literal notranslate">decimal.Decimal</code> type is uncommon in Python and so requires to adapt code to handle it.</li> </ul> </section> <section id="issues-caused-by-precision-loss"> <h3><a class="toc-backref" href="#issues-caused-by-precision-loss" role="doc-backlink">Issues caused by precision loss</a></h3> <section id="example-1-measure-time-delta-in-long-running-process"> <h4><a class="toc-backref" href="#example-1-measure-time-delta-in-long-running-process" role="doc-backlink">Example 1: measure time delta in long-running process</a></h4> A server is running for longer than 104 days. A clock is read before and after running a function to measure its performance to detect performance issues at runtime. Such benchmark only loses precision because of the float type used by clocks, not because of the clock resolution. On Python microbenchmarks, it is common to see function calls taking less than 100 ns. A difference of a few nanoseconds might become significant. </section> <section id="example-2-compare-times-with-different-resolution"> <h4><a class="toc-backref" href="#example-2-compare-times-with-different-resolution" role="doc-backlink">Example 2: compare times with different resolution</a></h4> Two programs “A” and “B” are running on the same system and use the system clock. The program A reads the system clock with nanosecond resolution and writes a timestamp with nanosecond resolution. The program B reads the timestamp with nanosecond resolution, but compares it to the system clock read with a worse resolution. To simplify the example, let’s say that B reads the clock with second resolution. If that case, there is a window of 1 second while the program B can see the timestamp written by A as “in the future”. Nowadays, more and more databases and filesystems support storing times with nanosecond resolution. <div class="admonition note"> Note This issue was already fixed for file modification time by adding the <code class="docutils literal notranslate">st_mtime_ns</code> field to the <code class="docutils literal notranslate">os.stat()</code> result, and by accepting nanoseconds in <code class="docutils literal notranslate">os.utime()</code>. This PEP proposes to generalize the fix. </div> </section> </section> <section id="cpython-enhancements-of-the-last-5-years"> <h3><a class="toc-backref" href="#cpython-enhancements-of-the-last-5-years" role="doc-backlink">CPython enhancements of the last 5 years</a></h3> Since the <a class="pep reference internal" href="../pep-0410/" title="PEP 410 – Use decimal.Decimal type for timestamps">PEP 410</a> was rejected: <ul class="simple"> <li>The <code class="docutils literal notranslate">os.stat_result</code> structure got 3 new fields for timestamps as nanoseconds (Python <code class="docutils literal notranslate">int</code>): <code class="docutils literal notranslate">st_atime_ns</code>, <code class="docutils literal notranslate">st_ctime_ns</code> and <code class="docutils literal notranslate">st_mtime_ns</code>.</li> <li>The <a class="pep reference internal" href="../pep-0418/" title="PEP 418 – Add monotonic time, performance counter, and process time functions">PEP 418</a> was accepted, Python 3.3 got 3 new clocks: <code class="docutils literal notranslate">time.monotonic()</code>, <code class="docutils literal notranslate">time.perf_counter()</code> and <code class="docutils literal notranslate">time.process_time()</code>.</li> <li>The CPython private “pytime” C API handling time now uses a new <code class="docutils literal notranslate">_PyTime_t</code> type: simple 64-bit signed integer (C <code class="docutils literal notranslate">int64_t</code>). The <code class="docutils literal notranslate">_PyTime_t</code> unit is an implementation detail and not part of the API. The unit is currently <code class="docutils literal notranslate">1 nanosecond</code>.</li> </ul> </section> <section id="existing-python-apis-using-nanoseconds-as-int"> <h3><a class="toc-backref" href="#existing-python-apis-using-nanoseconds-as-int" role="doc-backlink">Existing Python APIs using nanoseconds as int</a></h3> The <code class="docutils literal notranslate">os.stat_result</code> structure has 3 fields for timestamps as nanoseconds (<code class="docutils literal notranslate">int</code>): <code class="docutils literal notranslate">st_atime_ns</code>, <code class="docutils literal notranslate">st_ctime_ns</code> and <code class="docutils literal notranslate">st_mtime_ns</code>. The <code class="docutils literal notranslate">ns</code> parameter of the <code class="docutils literal notranslate">os.utime()</code> function accepts a <code class="docutils literal notranslate">(atime_ns: int, mtime_ns: int)</code> tuple: nanoseconds. </section> </section> <section id="changes"> <h2><a class="toc-backref" href="#changes" role="doc-backlink">Changes</a></h2> <section id="new-functions"> <h3><a class="toc-backref" href="#new-functions" role="doc-backlink">New functions</a></h3> This PEP adds six new functions to the <code class="docutils literal notranslate">time</code> module: <ul class="simple"> <li><code class="docutils literal notranslate">time.clock_gettime_ns(clock_id)</code></li> <li><code class="docutils literal notranslate">time.clock_settime_ns(clock_id, time: int)</code></li> <li><code class="docutils literal notranslate">time.monotonic_ns()</code></li> <li><code class="docutils literal notranslate">time.perf_counter_ns()</code></li> <li><code class="docutils literal notranslate">time.process_time_ns()</code></li> <li><code class="docutils literal notranslate">time.time_ns()</code></li> </ul> These functions are similar to the version without the <code class="docutils literal notranslate">_ns</code> suffix, but return a number of nanoseconds as a Python <code class="docutils literal notranslate">int</code>. For example, <code class="docutils literal notranslate">time.monotonic_ns() == int(time.monotonic() * 1e9)</code> if <code class="docutils literal notranslate">monotonic()</code> value is small enough to not lose precision. These functions are needed because they may return “large” timestamps, like <code class="docutils literal notranslate">time.time()</code> which uses the UNIX epoch as reference, and so their <code class="docutils literal notranslate">float</code>-returning variants are likely to lose precision at the nanosecond resolution. </section> <section id="unchanged-functions"> <h3><a class="toc-backref" href="#unchanged-functions" role="doc-backlink">Unchanged functions</a></h3> Since the <code class="docutils literal notranslate">time.clock()</code> function was deprecated in Python 3.3, no <code class="docutils literal notranslate">time.clock_ns()</code> is added. Python has other time-returning functions. No nanosecond variant is proposed for these other functions, either because their internal resolution is greater or equal to 1 us, or because their maximum value is small enough to not lose precision. For example, the maximum value of <code class="docutils literal notranslate">time.clock_getres()</code> should be 1 second. Examples of unchanged functions: <ul class="simple"> <li><code class="docutils literal notranslate">os</code> module: <code class="docutils literal notranslate">sched_rr_get_interval()</code>, <code class="docutils literal notranslate">times()</code>, <code class="docutils literal notranslate">wait3()</code> and <code class="docutils literal notranslate">wait4()</code></li> <li><code class="docutils literal notranslate">resource</code> module: <code class="docutils literal notranslate">ru_utime</code> and <code class="docutils literal notranslate">ru_stime</code> fields of <code class="docutils literal notranslate">getrusage()</code></li> <li><code class="docutils literal notranslate">signal</code> module: <code class="docutils literal notranslate">getitimer()</code>, <code class="docutils literal notranslate">setitimer()</code></li> <li><code class="docutils literal notranslate">time</code> module: <code class="docutils literal notranslate">clock_getres()</code></li> </ul> See also the <a class="reference internal" href="#annex-clocks-resolution-in-python">Annex: Clocks Resolution in Python</a>. A new nanosecond-returning flavor of these functions may be added later if an operating system exposes new functions providing better resolution. </section> </section> <section id="alternatives-and-discussion"> <h2><a class="toc-backref" href="#alternatives-and-discussion" role="doc-backlink">Alternatives and discussion</a></h2> <section id="sub-nanosecond-resolution"> <h3><a class="toc-backref" href="#sub-nanosecond-resolution" role="doc-backlink">Sub-nanosecond resolution</a></h3> <code class="docutils literal notranslate">time.time_ns()</code> API is not theoretically future-proof: if clock resolutions continue to increase below the nanosecond level, new Python functions may be needed. In practice, the 1 nanosecond resolution is currently enough for all structures returned by all common operating systems functions. Hardware clocks with a resolution better than 1 nanosecond already exist. For example, the frequency of a CPU TSC clock is the CPU base frequency: the resolution is around 0.3 ns for a CPU running at 3 GHz. Users who have access to such hardware and really need sub-nanosecond resolution can however extend Python for their needs. Such a rare use case doesn’t justify to design the Python standard library to support sub-nanosecond resolution. For the CPython implementation, nanosecond resolution is convenient: the standard and well supported <code class="docutils literal notranslate">int64_t</code> type can be used to store a nanosecond-precise timestamp. It supports a timespan of -292 years to +292 years. Using the UNIX epoch as reference, it therefore supports representing times since year 1677 to year 2262: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> 1970 - 2 ** 63 / (10 ** 9 * 3600 * 24 * 365.25) 1677.728976954687 >>> 1970 + 2 ** 63 / (10 ** 9 * 3600 * 24 * 365.25) 2262.271023045313 </pre></div> </div> </section> <section id="modifying-time-time-result-type"> <h3><a class="toc-backref" href="#modifying-time-time-result-type" role="doc-backlink">Modifying time.time() result type</a></h3> It was proposed to modify <code class="docutils literal notranslate">time.time()</code> to return a different number type with better precision. The <a class="pep reference internal" href="../pep-0410/" title="PEP 410 – Use decimal.Decimal type for timestamps">PEP 410</a> proposed to return <code class="docutils literal notranslate">decimal.Decimal</code> which already exists and supports arbitrary precision, but it was rejected. Apart from <code class="docutils literal notranslate">decimal.Decimal</code>, no portable real number type with better precision is currently available in Python. Changing the built-in Python <code class="docutils literal notranslate">float</code> type is out of the scope of this PEP. Moreover, changing existing functions to return a new type introduces a risk of breaking the backward compatibility even if the new type is designed carefully. </section> <section id="different-types"> <h3><a class="toc-backref" href="#different-types" role="doc-backlink">Different types</a></h3> Many ideas of new types were proposed to support larger or arbitrary precision: fractions, structures or 2-tuple using integers, fixed-point number, etc. See also the <a class="pep reference internal" href="../pep-0410/" title="PEP 410 – Use decimal.Decimal type for timestamps">PEP 410</a> for a previous long discussion on other types. Adding a new type requires more effort to support it, than reusing the existing <code class="docutils literal notranslate">int</code> type. The standard library, third party code and applications would have to be modified to support it. The Python <code class="docutils literal notranslate">int</code> type is well known, well supported, easy to manipulate, and supports all arithmetic operations such as <code class="docutils literal notranslate">dt = t2 - t1</code>. Moreover, taking/returning an integer number of nanoseconds is not a new concept in Python, as witnessed by <code class="docutils literal notranslate">os.stat_result</code> and <code class="docutils literal notranslate">os.utime(ns=(atime_ns, mtime_ns))</code>. <div class="admonition note"> Note If the Python <code class="docutils literal notranslate">float</code> type becomes larger (e.g. decimal128 or float128), the <code class="docutils literal notranslate">time.time()</code> precision will increase as well. </div> </section> <section id="different-api"> <h3><a class="toc-backref" href="#different-api" role="doc-backlink">Different API</a></h3> The <code class="docutils literal notranslate">time.time(ns=False)</code> API was proposed to avoid adding new functions. It’s an uncommon (and bad?) programming practice in Python to change the result type depending on a parameter. Different options were proposed to allow the user to choose the time resolution. If each Python module uses a different resolution, it can become difficult to handle different resolutions, instead of just seconds (<code class="docutils literal notranslate">time.time()</code> returning <code class="docutils literal notranslate">float</code>) and nanoseconds (<code class="docutils literal notranslate">time.time_ns()</code> returning <code class="docutils literal notranslate">int</code>). Moreover, as written above, there is no need for resolution better than 1 nanosecond in practice in the Python standard library. </section> <section id="a-new-module"> <h3><a class="toc-backref" href="#a-new-module" role="doc-backlink">A new module</a></h3> It was proposed to add a new <code class="docutils literal notranslate">time_ns</code> module containing the following functions: <ul class="simple"> <li><code class="docutils literal notranslate">time_ns.clock_gettime(clock_id)</code></li> <li><code class="docutils literal notranslate">time_ns.clock_settime(clock_id, time: int)</code></li> <li><code class="docutils literal notranslate">time_ns.monotonic()</code></li> <li><code class="docutils literal notranslate">time_ns.perf_counter()</code></li> <li><code class="docutils literal notranslate">time_ns.process_time()</code></li> <li><code class="docutils literal notranslate">time_ns.time()</code></li> </ul> The first question is whether the <code class="docutils literal notranslate">time_ns</code> module should expose exactly the same API (constants, functions, etc.) as the <code class="docutils literal notranslate">time</code> module. It can be painful to maintain two flavors of the <code class="docutils literal notranslate">time</code> module. How are users use supposed to make a choice between these two modules? If tomorrow, other nanosecond variants are needed in the <code class="docutils literal notranslate">os</code> module, will we have to add a new <code class="docutils literal notranslate">os_ns</code> module as well? There are functions related to time in many modules: <code class="docutils literal notranslate">time</code>, <code class="docutils literal notranslate">os</code>, <code class="docutils literal notranslate">signal</code>, <code class="docutils literal notranslate">resource</code>, <code class="docutils literal notranslate">select</code>, etc. Another idea is to add a <code class="docutils literal notranslate">time.ns</code> submodule or a nested-namespace to get the <code class="docutils literal notranslate">time.ns.time()</code> syntax, but it suffers from the same issues. </section> </section> <section id="annex-clocks-resolution-in-python"> <h2><a class="toc-backref" href="#annex-clocks-resolution-in-python" role="doc-backlink">Annex: Clocks Resolution in Python</a></h2> This annex contains the resolution of clocks as measured in Python, and not the resolution announced by the operating system or the resolution of the internal structure used by the operating system. <section id="script"> <h3><a class="toc-backref" href="#script" role="doc-backlink">Script</a></h3> Example of script to measure the smallest difference between two <code class="docutils literal notranslate">time.time()</code> and <code class="docutils literal notranslate">time.time_ns()</code> reads ignoring differences of zero: <div class="highlight-default notranslate"><div class="highlight"><pre>import math import time LOOPS = 10 ** 6 print("time.time_ns(): %s" % time.time_ns()) print("time.time(): %s" % time.time()) min_dt = [abs(time.time_ns() - time.time_ns()) for _ in range(LOOPS)] min_dt = min(filter(bool, min_dt)) print("min time_ns() delta: %s ns" % min_dt) min_dt = [abs(time.time() - time.time()) for _ in range(LOOPS)] min_dt = min(filter(bool, min_dt)) print("min time() delta: %s ns" % math.ceil(min_dt * 1e9)) </pre></div> </div> </section> <section id="linux"> <h3><a class="toc-backref" href="#linux" role="doc-backlink">Linux</a></h3> Clocks resolution measured in Python on Fedora 26 (kernel 4.12): <table class="docutils align-default"> <thead> <tr class="row-odd"><th class="head">Function</th> <th class="head">Resolution</th> </tr> </thead> <tbody> <tr class="row-even"><td>clock()</td> <td>1 us</td> </tr> <tr class="row-odd"><td>monotonic()</td> <td>81 ns</td> </tr> <tr class="row-even"><td>monotonic_ns()</td> <td>84 ns</td> </tr> <tr class="row-odd"><td>perf_counter()</td> <td>82 ns</td> </tr> <tr class="row-even"><td>perf_counter_ns()</td> <td>84 ns</td> </tr> <tr class="row-odd"><td>process_time()</td> <td>2 ns</td> </tr> <tr class="row-even"><td>process_time_ns()</td> <td>1 ns</td> </tr> <tr class="row-odd"><td>resource.getrusage()</td> <td>1 us</td> </tr> <tr class="row-even"><td>time()</td> <td>239 ns</td> </tr> <tr class="row-odd"><td>time_ns()</td> <td>84 ns</td> </tr> <tr class="row-even"><td>times().elapsed</td> <td>10 ms</td> </tr> <tr class="row-odd"><td>times().user</td> <td>10 ms</td> </tr> </tbody> </table> Notes on resolutions: <ul class="simple"> <li><code class="docutils literal notranslate">clock()</code> frequency is <code class="docutils literal notranslate">CLOCKS_PER_SECOND</code> which is 1,000,000 Hz (1 MHz): resolution of 1 us.</li> <li><code class="docutils literal notranslate">times()</code> frequency is <code class="docutils literal notranslate">os.sysconf("SC_CLK_TCK")</code> (or the <code class="docutils literal notranslate">HZ</code> constant) which is equal to 100 Hz: resolution of 10 ms.</li> <li><code class="docutils literal notranslate">resource.getrusage()</code>, <code class="docutils literal notranslate">os.wait3()</code> and <code class="docutils literal notranslate">os.wait4()</code> use the <code class="docutils literal notranslate">ru_usage</code> structure. The type of the <code class="docutils literal notranslate">ru_usage.ru_utime</code> and <code class="docutils literal notranslate">ru_usage.ru_stime</code> fields is the <code class="docutils literal notranslate">timeval</code> structure which has a resolution of 1 us.</li> </ul> </section> <section id="windows"> <h3><a class="toc-backref" href="#windows" role="doc-backlink">Windows</a></h3> Clocks resolution measured in Python on Windows 8.1: <table class="docutils align-default"> <thead> <tr class="row-odd"><th class="head">Function</th> <th class="head">Resolution</th> </tr> </thead> <tbody> <tr class="row-even"><td>monotonic()</td> <td>15 ms</td> </tr> <tr class="row-odd"><td>monotonic_ns()</td> <td>15 ms</td> </tr> <tr class="row-even"><td>perf_counter()</td> <td>100 ns</td> </tr> <tr class="row-odd"><td>perf_counter_ns()</td> <td>100 ns</td> </tr> <tr class="row-even"><td>process_time()</td> <td>15.6 ms</td> </tr> <tr class="row-odd"><td>process_time_ns()</td> <td>15.6 ms</td> </tr> <tr class="row-even"><td>time()</td> <td>894.1 us</td> </tr> <tr class="row-odd"><td>time_ns()</td> <td>318 us</td> </tr> </tbody> </table> The frequency of <code class="docutils literal notranslate">perf_counter()</code> and <code class="docutils literal notranslate">perf_counter_ns()</code> comes from <code class="docutils literal notranslate">QueryPerformanceFrequency()</code>. The frequency is usually 10 MHz: resolution of 100 ns. In old Windows versions, the frequency was sometimes 3,579,545 Hz (3.6 MHz): resolution of 279 ns. </section> <section id="analysis"> <h3><a class="toc-backref" href="#analysis" role="doc-backlink">Analysis</a></h3> The resolution of <code class="docutils literal notranslate">time.time_ns()</code> is much better than <code class="docutils literal notranslate">time.time()</code>: 84 ns (2.8x better) vs 239 ns on Linux and 318 us (2.8x better) vs 894 us on Windows. The <code class="docutils literal notranslate">time.time()</code> resolution will only become larger (worse) as years pass since every day adds 86,400,000,000,000 nanoseconds to the system clock, which increases the precision loss. The difference between <code class="docutils literal notranslate">time.perf_counter()</code>, <code class="docutils literal notranslate">time.monotonic()</code>, <code class="docutils literal notranslate">time.process_time()</code> and their respective nanosecond variants is not visible in this quick script since the script runs for less than 1 minute, and the uptime of the computer used to run the script was smaller than 1 week. A significant difference may be seen if uptime reaches 104 days or more. <code class="docutils literal notranslate">resource.getrusage()</code> and <code class="docutils literal notranslate">times()</code> have a resolution greater or equal to 1 microsecond, and so don’t need a variant with nanosecond resolution. <div class="admonition note"> Note Internally, Python starts <code class="docutils literal notranslate">monotonic()</code> and <code class="docutils literal notranslate">perf_counter()</code> clocks at zero on some platforms which indirectly reduce the precision loss. </div> </section> </section> <section id="links"> <h2><a class="toc-backref" href="#links" role="doc-backlink">Links</a></h2> <ul class="simple"> <li><a class="reference external" href="https://bugs.python.org/issue31784">bpo-31784: Implementation of the PEP 564</a></li> </ul> </section> <section id="copyright"> <h2><a class="toc-backref" href="#copyright" role="doc-backlink">Copyright</a></h2> This document has been placed in the public domain. </section> </section> <hr class="docutils" /> Source: <a class="reference external" href="https://github.com/python/peps/blob/main/peps/pep-0564.rst">https://github.com/python/peps/blob/main/peps/pep-0564.rst</a> Last modified: <a class="reference external" href="https://github.com/python/peps/commits/main/peps/pep-0564.rst">2023-09-09 17:39:29 GMT</a> </article> <nav id="pep-sidebar"> <h2>Contents</h2> <ul> <li><a class="reference internal" href="#abstract">Abstract</a></li> <li><a class="reference internal" href="#rationale">Rationale</a><ul> <li><a class="reference internal" href="#float-type-limited-to-104-days">Float type limited to 104 days</a></li> <li><a class="reference internal" href="#previous-rejected-pep">Previous rejected PEP</a></li> <li><a class="reference internal" href="#issues-caused-by-precision-loss">Issues caused by precision loss</a><ul> <li><a class="reference internal" href="#example-1-measure-time-delta-in-long-running-process">Example 1: measure time delta in long-running process</a></li> <li><a class="reference internal" href="#example-2-compare-times-with-different-resolution">Example 2: compare times with different resolution</a></li> </ul> </li> <li><a class="reference internal" href="#cpython-enhancements-of-the-last-5-years">CPython enhancements of the last 5 years</a></li> <li><a class="reference internal" href="#existing-python-apis-using-nanoseconds-as-int">Existing Python APIs using nanoseconds as int</a></li> </ul> </li> <li><a class="reference internal" href="#changes">Changes</a><ul> <li><a class="reference internal" href="#new-functions">New functions</a></li> <li><a class="reference internal" href="#unchanged-functions">Unchanged functions</a></li> </ul> </li> <li><a class="reference internal" href="#alternatives-and-discussion">Alternatives and discussion</a><ul> <li><a class="reference internal" href="#sub-nanosecond-resolution">Sub-nanosecond resolution</a></li> <li><a class="reference internal" href="#modifying-time-time-result-type">Modifying time.time() result type</a></li> <li><a class="reference internal" href="#different-types">Different types</a></li> <li><a class="reference internal" href="#different-api">Different API</a></li> <li><a class="reference internal" href="#a-new-module">A new module</a></li> </ul> </li> <li><a class="reference internal" href="#annex-clocks-resolution-in-python">Annex: Clocks Resolution in Python</a><ul> <li><a class="reference internal" href="#script">Script</a></li> <li><a class="reference internal" href="#linux">Linux</a></li> <li><a class="reference internal" href="#windows">Windows</a></li> <li><a class="reference internal" href="#analysis">Analysis</a></li> </ul> </li> <li><a class="reference internal" href="#links">Links</a></li> <li><a class="reference internal" href="#copyright">Copyright</a></li> </ul> <a id="source" href="https://github.com/python/peps/blob/main/peps/pep-0564.rst">Page Source (GitHub)</a> </nav> </section> <script src="../_static/colour_scheme.js"></script> <script src="../_static/wrap_tables.js"></script> <script src="../_static/sticky_banner.js"></script> </body> </html>