PEP 830: apply round-2 feedback

Updates the implementation to match the PEP revisions in
python/peps#4928

* Drop the ``us`` display format; ``-X traceback_timestamps`` with no
  value or ``=1`` now selects ``ns``.
* ``ns`` format now renders as seconds with nine fractional digits
  (``<@1776017178.687320256>``) instead of a raw integer with an ``ns``
  suffix.  Integer divmod is used to preserve full precision.
* The ``no_timestamp`` boolean on the traceback formatting APIs is
  replaced by a tri-state ``timestamps`` keyword: ``None`` follows the
  global config, ``False`` suppresses, ``True`` forces display of any
  non-zero ``__timestamp_ns__``.  The setting now propagates through
  ``__cause__``, ``__context__`` and exception-group members.
* MemoryError instances handed out from the free list receive a fresh
  timestamp at hand-out time; only the last-resort static singleton
  remains at 0.

Author: gpshead

Doc/c-api/init_config.rst

@@ -1905,9 +1905,9 @@ PyConfig
       If not ``NULL`` or an empty string, timestamps of exceptions are collected
       and will be displayed in the configured format. Acceptable values are:
 
-      * ``"us"``: Display timestamps in microseconds
-      * ``"ns"``: Display timestamps in nanoseconds
-      * ``"iso"``: Display timestamps in ISO-8601 format
+      * ``"ns"``: Display UTC seconds since the epoch with nanosecond resolution
+      * ``"iso"``: Display an ISO-8601 formatted UTC time with microsecond
+        resolution
       * ``""``: Collection and display is disabled.
 
       Set by the :option:`-X traceback_timestamps=FORMAT <-X>` command line

Doc/library/exceptions.rst

@@ -161,18 +161,22 @@ The following exceptions are used mostly as base classes for other exceptions.
 
    .. attribute:: __timestamp_ns__
 
-      The absolute time in nanoseconds at which this exception was instantiated
-      (usually: when it was raised).
-      Having the same accuracy and time epoch as :func:`time.time_ns`.
+      The absolute UTC time in nanoseconds at which this exception was
+      instantiated (usually: when it was raised), with the same accuracy and
+      epoch as :func:`time.time_ns`.
       Collection and display of these timestamps after the exception message in
       tracebacks is off by default but can be configured using the
       :envvar:`PYTHON_TRACEBACK_TIMESTAMPS` environment variable or the
       :option:`-X traceback_timestamps <-X>` command line option.  In
       applications with complicated exception chains and exception groups it
-      may be useful to help understand what happened when.  The value will be
-      ``0`` if a timestamp was not recorded.  :exc:`StopIteration` and
-      :exc:`StopAsyncIteration` never record timestamps as those are primarily
-      for control flow.
+      may be useful to help understand what happened when.
+
+      The value is ``0`` when a timestamp was not recorded.
+      :exc:`StopIteration` and :exc:`StopAsyncIteration` never record
+      timestamps as they are used primarily for control flow.
+
+      This attribute does not affect the result of :func:`str` or :func:`repr`
+      on the exception.
 
       With ``PYTHON_TRACEBACK_TIMESTAMPS=iso`` in the environment ::
 
@@ -186,7 +190,7 @@ The following exceptions are used mostly as base classes for other exceptions.
          Traceback (most recent call last):
            File "<python-input-0>", line 1, in <module>
              raise RuntimeError("example")
-         RuntimeError: example <@1739172733527638530ns>
+         RuntimeError: example <@1739172733.527638530>
 
       .. versionadded:: next
 

Doc/library/sys.rst

@@ -655,7 +655,7 @@ always available. Unless explicitly noted otherwise, all variables are read-only
       * - .. attribute:: flags.traceback_timestamps
         - :option:`-X traceback_timestamps <-X>` and
           :envvar:`PYTHON_TRACEBACK_TIMESTAMPS`.  This is a string containing
-          the selected format (``us``, ``ns``, ``iso``),  or an empty string
+          the selected format (``ns`` or ``iso``), or an empty string
           when disabled.
 
    .. versionchanged:: 3.2

Doc/library/traceback.rst

@@ -79,7 +79,7 @@ Module-Level Functions
 
 
 .. function:: print_exception(exc, /[, value, tb], limit=None, \
-                          file=None, chain=True, \*, no_timestamp=False)
+                          file=None, chain=True, \*, timestamps=None)
 
    Print exception information and stack trace entries from
    :ref:`traceback object <traceback-objects>`
@@ -108,11 +108,14 @@ Module-Level Functions
    printed as well, like the interpreter itself does when printing an unhandled
    exception.
 
-   If *no_timestamp* is ``True`` and a traceback timestamp format is enabled via the
-   :envvar:`PYTHON_TRACEBACK_TIMESTAMPS` environment variable or the
-   :option:`-X traceback_timestamps <-X>` option, any timestamp after the exception
-   message will be omitted. This is useful for tests or other situations where
-   you need consistent output regardless of when exceptions occur.
+   The *timestamps* argument controls whether the
+   :attr:`~BaseException.__timestamp_ns__` of each exception is appended after
+   its message.  When ``None`` (the default), the global configuration set by
+   :envvar:`PYTHON_TRACEBACK_TIMESTAMPS` or
+   :option:`-X traceback_timestamps <-X>` is followed.  When ``False``,
+   timestamps are never shown.  When ``True``, any non-zero
+   ``__timestamp_ns__`` is shown regardless of the global configuration, using
+   the configured format if one is set and the ``ns`` format otherwise.
 
    .. versionchanged:: 3.5
       The *etype* argument is ignored and inferred from the type of *value*.
@@ -122,7 +125,7 @@ Module-Level Functions
       positional-only.
 
    .. versionchanged:: next
-      The *no_timestamp* keyword only argument was added.
+      The *timestamps* keyword-only argument was added.
 
 
 .. function:: print_exc(limit=None, file=None, chain=True)
@@ -191,7 +194,7 @@ Module-Level Functions
 
 
 .. function:: format_exception_only(exc, /[, value], \*, show_group=False, \
-                    no_timestamp=False)
+                    timestamps=None)
 
    Format the exception part of a traceback using an exception value such as
    given by :data:`sys.last_value`.  The return value is a list of strings, each
@@ -209,11 +212,8 @@ Module-Level Functions
    :exc:`BaseExceptionGroup`, the nested exceptions are included as
    well, recursively, with indentation relative to their nesting depth.
 
-   If *no_timestamp* is ``True`` and a traceback timestamp formatting is enabled
-   via the :envvar:`PYTHON_TRACEBACK_TIMESTAMPS` environment variable or the
-   :option:`-X traceback_timestamps <-X>` command line option, any timestamp
-   after the exception message will be omitted. This is useful for tests or
-   other situations where you need canonical output.
+   The *timestamps* argument has the same meaning as for
+   :func:`print_exception`.
 
    .. versionchanged:: 3.10
       The *etype* parameter has been renamed to *exc* and is now
@@ -227,24 +227,20 @@ Module-Level Functions
       *show_group* parameter was added.
 
    .. versionchanged:: next
-      The *no_timestamp* keyword only argument was added.
+      The *timestamps* keyword-only argument was added.
 
 
 .. function:: format_exception(exc, /[, value, tb], limit=None, chain=True, \
-                 \*, no_timestamp=False)
+                 \*, timestamps=None)
 
    Format a stack trace and the exception information.  The arguments  have the
    same meaning as the corresponding arguments to :func:`print_exception`.  The
    return value is a list of strings, each ending in a newline and some
    containing internal newlines.  When these lines are concatenated and printed,
    exactly the same text is printed as does :func:`print_exception`.
 
-   If *no_timestamp* is ``True`` and a traceback timestamp formatting is enabled
-   via the :envvar:`PYTHON_TRACEBACK_TIMESTAMPS` environment variable or the
-   :option:`-X traceback_timestamps <-X>` command line option, any timestamp
-   after the exception message will be omitted. This is useful for tests or
-   other situations where you need consistent output regardless of when
-   exceptions occur.
+   The *timestamps* argument has the same meaning as for
+   :func:`print_exception`.
 
    .. versionchanged:: 3.5
       The *etype* argument is ignored and inferred from the type of *value*.
@@ -254,7 +250,7 @@ Module-Level Functions
       :func:`print_exception`.
 
    .. versionchanged:: next
-      The *no_timestamp* keyword only argument was added.
+      The *timestamps* keyword-only argument was added.
 
 
 .. function:: format_exc(limit=None, chain=True)
@@ -329,7 +325,7 @@ storing this information by avoiding holding references to
 In addition, they expose more options to configure the output compared to
 the module-level functions described above.
 
-.. class:: TracebackException(exc_type, exc_value, exc_traceback, \*, limit=None, lookup_lines=True, capture_locals=False, compact=False, max_group_width=15, max_group_depth=10, no_timestamp=False)
+.. class:: TracebackException(exc_type, exc_value, exc_traceback, \*, limit=None, lookup_lines=True, capture_locals=False, compact=False, max_group_width=15, max_group_depth=10, timestamps=None)
 
    Capture an exception for later rendering. The meaning of *limit*,
    *lookup_lines* and *capture_locals* are as for the :class:`StackSummary`
@@ -349,9 +345,13 @@ the module-level functions described above.
    group's exceptions array. The formatted output is truncated when either
    limit is exceeded.
 
-   If *no_timestamp* is ``True`` the ``__timestamp_ns__`` attribute from the
-   exception will not be rendered when formatting this
-   :class:`!TracebackException`.
+   The *timestamps* argument controls whether each exception's
+   :attr:`~BaseException.__timestamp_ns__` is captured for later rendering.
+   When ``None`` (the default), the global configuration set by
+   :envvar:`PYTHON_TRACEBACK_TIMESTAMPS` or
+   :option:`-X traceback_timestamps <-X>` is followed.  When ``False``,
+   timestamps are never shown.  When ``True``, any non-zero
+   ``__timestamp_ns__`` is shown regardless of the global configuration.
 
    .. versionchanged:: 3.10
       Added the *compact* parameter.
@@ -360,7 +360,7 @@ the module-level functions described above.
       Added the *max_group_width* and *max_group_depth* parameters.
 
    .. versionchanged:: next
-      Added the *no_timestamp* parameter.
+      Added the *timestamps* parameter.
 
    .. attribute:: __cause__
 

Doc/using/cmdline.rst

@@ -713,12 +713,12 @@ Miscellaneous options
 
      .. versionadded:: 3.15
 
-   * :samp:`-X traceback_timestamps=[us|ns|iso|0|1]` enables or configures timestamp
+   * :samp:`-X traceback_timestamps=[ns|iso|0|1]` enables or configures timestamp
      display in exception tracebacks. When enabled, each exception's traceback
      will include a timestamp showing when the exception occurred. The format
-     options are: ``us`` (microseconds), ``ns``
-     (nanoseconds), ``iso`` (ISO-8601 formatted time), ``0`` (disable timestamps),
-     and ``1`` (equivalent to ``us``). See also :envvar:`PYTHON_TRACEBACK_TIMESTAMPS`.
+     options are: ``ns`` (seconds since the epoch with nanosecond resolution),
+     ``iso`` (ISO-8601 formatted UTC time), ``0`` (disable timestamps),
+     and ``1`` (equivalent to ``ns``). See also :envvar:`PYTHON_TRACEBACK_TIMESTAMPS`.
 
      .. versionadded:: next
 
@@ -1440,9 +1440,9 @@ conflict.
    by the runtime will be annotated with the timestamp of each exception.  The
    values control the format of the timestamp:
 
-   * ``us`` or ``1``: Prints decimal timestamps with microsecond precision.
-   * ``ns``: Prints the raw timestamp in nanoseconds.
-   * ``iso``: Prints the timestamp formatted by :meth:`~datetime.datetime.isoformat` (also microsecond precision).
+   * ``ns`` or ``1``: Prints UTC seconds since the epoch with nanosecond
+     resolution.
+   * ``iso``: Prints an ISO-8601 formatted UTC time with microsecond resolution.
    * ``0``: Explicitly disables timestamps.
 
    When unset, timestamps are disabled by default. The time is not recorded on

Lib/doctest.py

@@ -273,7 +273,7 @@ def _exception_traceback(exc_info):
     # Get a traceback message.
     excout = StringIO()
     exc_type, exc_val, exc_tb = exc_info
-    traceback.print_exception(exc_type, exc_val, exc_tb, file=excout, no_timestamp=True)
+    traceback.print_exception(exc_type, exc_val, exc_tb, file=excout, timestamps=False)
     return excout.getvalue()
 
 # Override some StringIO methods.
@@ -1449,7 +1449,7 @@ def __run(self, test, compileflags, out):
 
             # The example raised an exception:  check if it was expected.
             else:
-                formatted_ex = traceback.format_exception_only(*exc_info[:2], no_timestamp=True)
+                formatted_ex = traceback.format_exception_only(*exc_info[:2], timestamps=False)
                 if issubclass(exc_info[0], SyntaxError):
                     # SyntaxError / IndentationError is special:
                     # we don't care about the carets / suggestions / etc

Lib/test/support/__init__.py

@@ -3039,17 +3039,15 @@ def no_traceback_timestamps():
 
     with (
         swap_attr(traceback, "_TIMESTAMP_FORMAT", ""),
+        # The C fallback display path in pythonrun.c gates on
+        # PyCallable_Check(_timestamp_formatter), so None is needed here in
+        # addition to the empty format string.
+        swap_attr(traceback, "_timestamp_formatter", None),
         EnvironmentVarGuard() as env,
     ):
         # This prevents it from being on in child processes.
         env.unset("PYTHON_TRACEBACK_TIMESTAMPS")
-        # Silence our other-path pythonrun.c print_exception_message().
-        tf = getattr(traceback, "_timestamp_formatter", "Nope!")
-        if tf != "Nope!":
-            del traceback._timestamp_formatter
         yield
-        if tf != "Nope!":
-            traceback._timestamp_formatter = tf
 
 
 def force_no_traceback_timestamps(func):

Lib/test/test_code_module.py

@@ -158,7 +158,7 @@ def test_sysexcepthook(self):
         self.assertIs(self.sysmod.last_traceback, self.sysmod.last_value.__traceback__)
         self.assertIs(self.sysmod.last_exc, self.sysmod.last_value)
         self.assertEqual(
-            traceback.format_exception(self.sysmod.last_exc, no_timestamp=True),
+            traceback.format_exception(self.sysmod.last_exc, timestamps=False),
             [
             'Traceback (most recent call last):\n',
             '  File "<console>", line 1, in <module>\n',
@@ -183,7 +183,7 @@ def test_sysexcepthook_syntax_error(self):
         self.assertIsNone(self.sysmod.last_value.__traceback__)
         self.assertIs(self.sysmod.last_exc, self.sysmod.last_value)
         self.assertEqual(
-            traceback.format_exception(self.sysmod.last_exc, no_timestamp=True),
+            traceback.format_exception(self.sysmod.last_exc, timestamps=False),
             [
             '  File "<console>", line 2\n',
             '    x = ?\n',
@@ -205,7 +205,7 @@ def test_sysexcepthook_indentation_error(self):
         self.assertIsNone(self.sysmod.last_value.__traceback__)
         self.assertIs(self.sysmod.last_exc, self.sysmod.last_value)
         self.assertEqual(
-            traceback.format_exception(self.sysmod.last_exc, no_timestamp=True),
+            traceback.format_exception(self.sysmod.last_exc, timestamps=False),
             [
             '  File "<console>", line 1\n',
             '    1\n',