gh-132502: Implements PEP-830 adding timestamps to tracebacks

.github/workflows/build.yml

@@ -259,6 +259,7 @@ jobs:
  bolt-optimizations: ${{ matrix.bolt }}
  free-threading: ${{ matrix.free-threading }}
  os: ${{ matrix.os }}
+ traceback_timestamps: ${{ matrix.os == 'ubuntu-24.04-arm' && matrix.bolt == false && 'ns' || '' }}
  test-opts: ${{ matrix.test-opts || '' }}
 
  build-ubuntu-ssltests:
@@ -726,3 +727,4 @@ jobs:
  ${{ !fromJSON(needs.build-context.outputs.run-emscripten) && 'build-emscripten,' || '' }}
  ${{ !fromJSON(needs.build-context.outputs.run-wasi) && 'build-wasi,' || '' }}
  jobs: ${{ toJSON(needs) }}
+ traceback_timestamps: 'iso'

.github/workflows/reusable-macos.yml

@@ -11,6 +11,10 @@ on:
  description: OS to run the job
  required: true
  type: string
+ traceback_timestamps:
+ description: Set to us|1|ns|iso to enable printing timestamps on exceptions in tracebacks (for feature coverage)
+ required: false
+ type: string
 
 permissions:
  contents: read
@@ -29,6 +33,7 @@ jobs:
  HOMEBREW_NO_INSTALL_CLEANUP: 1
  HOMEBREW_NO_INSTALLED_DEPENDENTS_CHECK: 1
  PYTHONSTRICTEXTENSIONBUILD: 1
+ PYTHON_TRACEBACK_TIMESTAMPS: ${{ inputs.traceback_timestamps }}
  TERM: linux
  steps:
  - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2

.github/workflows/reusable-ubuntu.yml

@@ -14,9 +14,13 @@ on:
  type: boolean
  default: false
  os:
- description: OS to run the job
- required: true
- type: string
+ description: OS to run the job
+ required: true
+ type: string
+ traceback_timestamps:
+ description: Set to us|1|ns|iso to enable printing timestamps on exceptions in tracebacks (for feature coverage)
+ required: false
+ type: string
  test-opts:
  description: Extra options to pass to the test runner via TESTOPTS
  required: false
@@ -38,6 +42,7 @@ jobs:
  OPENSSL_VER: 3.5.5
  PYTHONSTRICTEXTENSIONBUILD: 1
  TERM: linux
+ PYTHON_TRACEBACK_TIMESTAMPS: ${{ inputs.traceback_timestamps }}
  steps:
  - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
  with:

.github/workflows/reusable-windows.yml

@@ -32,6 +32,7 @@ jobs:
  timeout-minutes: 60
  env:
  ARCH: ${{ inputs.arch }}
+ PYTHON_TRACEBACK_TIMESTAMPS: 'ns'
  steps:
  - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
  with:

Doc/c-api/init_config.rst

@@ -493,6 +493,10 @@ Configuration Options
  - :c:member:`tracemalloc <PyConfig.tracemalloc>`
  - ``int``
  - Read-only
+ * - ``"traceback_timestamps"``
+ - :c:member:`traceback_timestamps <PyConfig.traceback_timestamps>`
+ - ``str``
+ - Read-only
  * - ``"use_environment"``
  - :c:member:`use_environment <PyConfig.use_environment>`
  - ``bool``
@@ -1894,6 +1898,25 @@ PyConfig
 
  Default: ``-1`` in Python mode, ``0`` in isolated mode.
 
+ .. c:member:: wchar_t* traceback_timestamps
+
+ Format of timestamps shown in tracebacks.
+
+ If not ``NULL`` or an empty string, timestamps of exceptions are collected
+ and will be displayed in the configured format. Acceptable values are:
+
+ * ``"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
+ option or the :envvar:`PYTHON_TRACEBACK_TIMESTAMPS` environment variable.
+
+ Default: ``NULL`` (timestamps disabled).
+
+ .. versionadded:: next
+
  .. c:member:: int perf_profiling
 
  Enable the Linux ``perf`` profiler support?

Doc/library/doctest.rst

@@ -539,6 +539,11 @@ Some details you should read once, but won't need to remember:
  everything following the leftmost colon and any module information in the
  exception name is ignored.
 
+* When the :const:`IGNORE_EXCEPTION_TIMESTAMPS` doctest option is specified,
+ timestamps of the formats that :envvar:`PYTHON_TRACEBACK_TIMESTAMPS`
+ environment variable could append to exception messages are stripped from
+ tracebacks generated by the code under test before comparison.
+
 * The interactive shell omits the traceback header line for some
  :exc:`SyntaxError`\ s. But doctest uses the traceback header line to
  distinguish exceptions from non-exceptions. So in the rare case where you need
@@ -661,6 +666,22 @@ doctest decides whether actual output matches an example's expected output:
  to the module containing the exception under test.
 
 
+.. data:: IGNORE_EXCEPTION_TIMESTAMPS
+
+ When the :envvar:`PYTHON_TRACEBACK_TIMESTAMPS` environment variable is set,
+ exception and warning messages rendered in tracebacks may have a timestamp
+ value appended after the message. This strips all possible formats of that
+ timestamp tag that may be appended to an exception message in generated
+ tracebacks before comparing.
+
+ :const:`ELLIPSIS` and :const:`IGNORE_EXCEPTION_DETAIL` could also be used to
+ avoid matching those. This can be cleaner when you need to test specific
+ details of exception messages.
+
+ .. versionadded:: next
+ :const:`IGNORE_EXCEPTION_TIMESTAMPS` was added.
+
+
 .. data:: SKIP
 
  When specified, do not run the example at all. This can be useful in contexts

Doc/library/exceptions.rst

@@ -159,6 +159,41 @@ The following exceptions are used mostly as base classes for other exceptions.
 
  .. versionadded:: 3.11
 
+ .. attribute:: __timestamp_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 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 ::
+
+ Traceback (most recent call last):
+ File "<python-input-0>", line 1, in <module>
+ raise RuntimeError("example")
+ RuntimeError: example <@2025-02-08T01:21:28.675309Z>
+
+ With ``PYTHON_TRACEBACK_TIMESTAMPS=ns`` in the environment ::
+
+ Traceback (most recent call last):
+ File "<python-input-0>", line 1, in <module>
+ raise RuntimeError("example")
+ RuntimeError: example <@1739172733.527638530>
+
+ .. versionadded:: next
+
 
 .. exception:: Exception
 

Doc/library/sys.rst

@@ -652,6 +652,11 @@ always available. Unless explicitly noted otherwise, all variables are read-only
  - :option:`-X context_aware_warnings <-X>` and
  :envvar:`PYTHON_CONTEXT_AWARE_WARNINGS`
 
+ * - .. attribute:: flags.traceback_timestamps
+ - :option:`-X traceback_timestamps <-X>` and
+ :envvar:`PYTHON_TRACEBACK_TIMESTAMPS`. This is a string containing
+ the selected format (``ns`` or ``iso``), or an empty string
+ when disabled.
 
  .. versionchanged:: 3.2
  Added ``quiet`` attribute for the new :option:`-q` flag.
@@ -688,6 +693,9 @@ always available. Unless explicitly noted otherwise, all variables are read-only
  .. versionchanged:: 3.14
  Added the ``context_aware_warnings`` attribute.
 
+ .. versionchanged:: next
+ Added the ``traceback_timestamps`` attribute.
+
 
 .. data:: float_info