Update PEP to match implementation and resolve open issues

- Remove LLM-isms: rewrite bold-numbered lists as plain bullets,
  fix "key insight" phrasing
- Fix type description: int64_t in C struct, not generic "integer"
- Fix exception name: AsyncStopIteration -> StopAsyncIteration
- Remove tutorial from How to Teach This (not needed for advanced feature)
- Expand Backwards Compatibility with explicit pickle format details
- Add colorized output mention to Display Format
- Document control flow check uses C type pointer identity
- Resolve all 5 open issues into Rejected Ideas:
  runtime API, retroactive timestamps, custom formats,
  always-collect, configurable control flow exception set
- Rewrite "Always Collecting" as collection vs display distinction

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: gpshead

peps/pep-08XX.rst

@@ -30,26 +30,23 @@ patterns and exception groups introduced in :pep:`654`, understanding the
 temporal relationships between exceptions has become increasingly important.
 Consider the following scenarios:
 
-1. **Async servers with exception groups**: When multiple exceptions are caught
-   and grouped together, it's often difficult to understand which exception
-   occurred first and how they relate temporally to each other and to external
-   events in the system.
+- When multiple exceptions are caught and grouped together, it can be difficult
+  to understand which exception occurred first and how they relate temporally
+  to each other and to external events in the system.
 
-2. **Distributed systems debugging**: When correlating exceptions across
-   different services, having precise timestamps allows developers to match
-   exceptions with logs from other systems, making root cause analysis more
-   straightforward.
+- When correlating exceptions across different services, precise timestamps
+  allow developers to match exceptions with logs from other systems, making
+  root cause analysis more straightforward.
 
-3. **Complex exception chains**: In applications with deep exception chains
-   (exceptions raised during handling of other exceptions), timestamps help
-   clarify the sequence of events that led to the final error state.
+- In applications with deep exception chains (exceptions raised during handling
+  of other exceptions), timestamps help clarify the sequence of events that
+  led to the final error state.
 
-4. **Performance debugging**: Timestamps can reveal performance issues, such as
-   delays between exception creation and handling, or help identify timeout-related
-   problems.
+- Timestamps can reveal performance issues such as delays between exception
+  creation and handling, or help identify timeout-related problems.
 
 Currently, developers must manually add timing information to exception messages
-or use external logging frameworks, which can be cumbersome and inconsistent.
+or use external logging frameworks, which is cumbersome and inconsistent.
 This PEP proposes a built-in, standardized approach.
 
 
@@ -144,63 +141,60 @@ Why Exception Groups Need Timestamps
 While exception groups are conceptually "unrelated" exceptions that happen to be
 raised together, in practice they often have important temporal relationships:
 
-1. **Causality isn't always explicit**: When multiple services fail in sequence,
-   one failure might trigger cascading failures in seemingly unrelated services.
-   Without timestamps, these cascade patterns are invisible. For example, a
-   database connection pool exhaustion might cause multiple "unrelated" query
-   failures across different services.
+- Causality isn't always explicit.  When multiple services fail in sequence,
+  one failure might trigger cascading failures in seemingly unrelated services.
+  Without timestamps, these cascade patterns are invisible.  For example, a
+  database connection pool exhaustion might cause multiple "unrelated" query
+  failures across different services.
 
-2. **Concurrent doesn't mean simultaneous**: Tasks in an exception group may
-   start concurrently but fail at very different times. A service that fails
-   after 100ms versus one that fails after 5 seconds tells a different story
-   about what went wrong - the first might be a validation error, the second
-   a timeout.
+- Concurrent doesn't mean simultaneous.  Tasks in an exception group may
+  start concurrently but fail at very different times.  A service that fails
+  after 100ms versus one that fails after 5 seconds tells a different story
+  about what went wrong -- the first might be a validation error, the second
+  a timeout.
 
-3. **Debugging distributed systems**: In microservice architectures, exception
-   groups often collect failures from multiple remote services. Timestamps allow
-   correlation with external observability tools (logs, metrics, traces) that
-   are essential for understanding the full picture.
+- In microservice architectures, exception groups often collect failures from
+  multiple remote services.  Timestamps allow correlation with external
+  observability tools (logs, metrics, traces) that are essential for
+  understanding the full picture.
 
-4. **Performance analysis**: Even for "unrelated" exceptions, knowing their
-   temporal distribution helps identify performance bottlenecks and timeout
-   configurations that need adjustment.
+- Even for "unrelated" exceptions, knowing their temporal distribution helps
+  identify performance bottlenecks and timeout configurations that need
+  adjustment.
 
 
 Why Not Use ``.add_note()`` When Catching?
 --------------------------------------------
 
-A common question is why we don't simply use :pep:`678`'s ``.add_note()`` to add
-timestamps when exceptions are caught and grouped. This approach has several
-significant drawbacks:
+A common question is why not simply use :pep:`678`'s ``.add_note()`` to add
+timestamps when exceptions are caught and grouped.  This approach has several
+drawbacks:
 
-1. **Not all exceptions are caught**: Exceptions that propagate to the top level
-   or are logged directly never get the opportunity to have notes added. The
-   timestamp of when an error occurred is lost forever.
+- Not all exceptions are caught.  Exceptions that propagate to the top level
+  or are logged directly never get the opportunity to have notes added.
 
-2. **Timing accuracy**: Adding a note when catching introduces variable delay.
-   The timestamp would reflect when the exception was caught and processed, not
-   when it actually occurred. In async code with complex exception handling,
-   this delay can be significant and misleading.
+- Adding a note when catching introduces variable delay.  The timestamp would
+  reflect when the exception was caught and processed, not when it actually
+  occurred.  In async code with complex exception handling, this delay can be
+  significant and misleading.
 
-3. **Inconsistent application**: Relying on exception handlers to add timestamps
-   means some exceptions get timestamps and others don't, depending on code
-   paths. This inconsistency makes debugging harder, not easier.
+- Relying on exception handlers to add timestamps means some exceptions get
+  timestamps and others don't, depending on code paths.
 
-4. **Performance overhead**: Creating note strings for every caught exception
-   adds overhead even when timestamps aren't being displayed. With the proposed
-   approach, formatting only happens when tracebacks are rendered.
+- Creating note strings for every caught exception adds overhead even when
+  timestamps aren't being displayed.  With the proposed approach, formatting
+  only happens when tracebacks are rendered.
 
-5. **Complexity burden**: Every exception handler that wants timing information
-   would need to remember to add notes. This is error-prone and adds boilerplate
-   to exception handling code.
+- Every exception handler that wants timing information would need to remember
+  to add notes.  This is error-prone and adds boilerplate.
 
-6. **Lost original timing**: By the time an exception is caught, the original
-   failure moment is lost. In retry loops or complex error handling, the catch
-   point might be seconds or minutes after the actual error.
+- By the time an exception is caught, the original failure moment is lost.
+  In retry loops or complex error handling, the catch point might be seconds
+  or minutes after the actual error.
 
-The key insight is that **when** an exception is created is intrinsic, immutable
-information about that exception - just like its type and message. This information
-should be captured at the source, not added later by consumers.
+When an exception is created is intrinsic, immutable information about that
+exception, just like its type and message. It should be captured at the source,
+not added later by consumers.
 
 
 Rationale
@@ -210,19 +204,19 @@ The decision to add timestamps directly to exception objects rather than using
 alternative approaches (such as exception notes from :pep:`678`) was driven by
 several factors:
 
-1. **Performance**: Adding timestamps as notes would require creating string
-   and list objects for every exception, even when timestamps aren't being
-   displayed. The proposed approach stores a single integer (nanoseconds since
-   epoch) and only formats it when needed.
+- Adding timestamps as notes would require creating string and list objects for
+  every exception, even when timestamps aren't being displayed.  The proposed
+  approach stores a single ``int64_t`` in the C struct (nanoseconds since epoch)
+  and only formats it when needed.
 
-2. **Consistency**: Having a standardized timestamp attribute ensures consistent
-   formatting and behavior across the Python ecosystem.
+- A standardized timestamp attribute ensures consistent formatting and behavior
+  across the Python ecosystem.
 
-3. **Backwards compatibility**: The feature is entirely opt-in, with no impact
-   on existing code unless explicitly enabled.
+- The feature is entirely opt-in, with no impact on existing code unless
+  explicitly enabled.
 
-4. **Simplicity**: The implementation is straightforward and doesn't require
-   changes to exception handling semantics.
+- The implementation is straightforward and doesn't require changes to exception
+  handling semantics.
 
 
 Specification
@@ -248,14 +242,17 @@ To avoid performance impacts on normal control flow, timestamps will **not** be
 collected for certain exception types even when the feature is enabled. By default:
 
 - ``StopIteration``
-- ``AsyncStopIteration``
+- ``StopAsyncIteration``
 
 These exceptions are frequently used for control flow in iterators and async
-iterators. However, other projects also use custom exceptions for control flow
-(e.g., Sphinx's ``Skip`` exception), making the need for configurability clear.
+iterators and are raised at extremely high frequency during normal operation.
+The check uses C type pointer identity (not ``isinstance``) so it adds
+negligible overhead to exception creation.
 
-The current implementation hard-codes these two exceptions for performance
-reasons. See Open Issues for discussion about making this configurable.
+Some third-party projects also use custom exceptions for control flow (e.g.,
+Sphinx's ``Skip`` exception), but these are not performance-critical enough
+to warrant special handling. See Rejected Ideas for discussion of making
+this set configurable.
 
 Configuration
 -------------
@@ -298,6 +295,9 @@ Example with ``PYTHON_TRACEBACK_TIMESTAMPS=iso``::
         raise OSError(2, "on a cloudy day")
     FileNotFoundError: [Errno 2] on a cloudy day <@2025-02-01T20:43:01.026176Z>
 
+When colorized traceback output is enabled, the timestamp is rendered in a
+muted color to keep it visually distinct from the exception message.
+
 Traceback Module Updates
 ------------------------
 
@@ -326,11 +326,20 @@ Backwards Compatibility
 
 This proposal maintains full backwards compatibility:
 
-1. The feature is disabled by default
-2. Existing exception handling code continues to work unchanged
-3. The new attribute is only set when the feature is explicitly enabled
-4. Pickle/unpickle of exceptions works correctly with the new attribute
-5. Third-party exception formatting libraries can ignore the attribute if desired
+1. The feature is disabled by default.
+2. Existing exception handling code continues to work unchanged.
+3. The ``__timestamp_ns__`` attribute is always readable as a C member
+   descriptor on all ``BaseException`` instances, returning ``0`` when
+   timestamps are not collected.  It is only populated with a nonzero
+   value when the feature is enabled.
+4. Pickle format is unchanged when timestamps are disabled: exceptions
+   pickle as the traditional 2-tuple ``(type, args)``.  When a nonzero
+   timestamp is present, the exception pickles as a 3-tuple
+   ``(type, args, state_dict)`` with ``__timestamp_ns__`` included in
+   the state dictionary.  Older Python versions will unpickle these
+   correctly, simply setting the extra attribute via ``__setstate__``.
+5. Third-party exception formatting libraries can ignore the attribute
+   if desired.
 
 
 Security Implications
@@ -354,8 +363,7 @@ The feature should be documented in:
 
 1. The Python documentation for the ``exceptions`` module
 2. The ``traceback`` module documentation
-3. The Python tutorial section on exception handling (as an advanced topic)
-4. The command-line interface documentation
+3. The command-line interface documentation
 
 Example use cases should focus on:
 
@@ -375,7 +383,7 @@ The implementation includes:
 - Core exception object changes to add the ``__timestamp_ns__`` attribute
 - Traceback formatting updates to display timestamps
 - Configuration through environment variables and command-line options
-- Special handling for ``StopIteration`` and ``AsyncStopIteration``
+- Special handling for ``StopIteration`` and ``StopAsyncIteration``
 - Comprehensive test coverage
 - Documentation updates
 
@@ -393,15 +401,64 @@ An alternative approach would be to use the exception notes feature from
 2. The performance impact would be significant even when not displaying timestamps
 3. It would make the timestamp less structured and harder to process programmatically
 
-Always Collecting Timestamps
------------------------------
-
-Collecting timestamps for all exceptions unconditionally was considered but
-rejected due to:
-
-1. Performance overhead for exceptions used in control flow
-2. Unnecessary memory usage for the vast majority of use cases
-3. Potential security concerns in production environments
+Always Collecting vs. Always Displaying
+----------------------------------------
+
+It is important to distinguish between *collecting* timestamps (calling
+``clock_gettime`` during exception instantiation) and *displaying* them in
+formatted tracebacks.
+
+Always displaying timestamps was rejected because it adds noise to traceback
+output that most users do not need.
+
+Always collecting timestamps (even when display is disabled) was considered.
+The ``int64_t`` field exists in the ``BaseException`` C struct regardless,
+so there is no additional memory cost.  The ``clock_gettime`` call itself is
+cheap for most exceptions.  However, there was no compelling reason to collect
+timestamps when they would never be displayed, so collection is currently tied
+to the display configuration.  This could be revisited as a separate future
+feature if programmatic access to exception timestamps proves useful
+independent of traceback display.
+
+Runtime API for Enabling/Disabling Timestamps
+----------------------------------------------
+
+A Python API to programmatically enable or disable timestamps at runtime was
+considered and rejected.  There is no obvious use case, and global behavior
+changes at runtime are problematic for reasoning about program state.  The
+feature is configured at startup via environment variable or command-line
+option and remains fixed for the lifetime of the process.
+
+Retroactive Timestamps on Existing Exceptions
+-----------------------------------------------
+
+Adding timestamps to already-created exception objects was considered and
+rejected.  The timestamp represents when the exception was instantiated;
+adding one after the fact would be misleading.  Users who need to annotate
+existing exceptions with timing information can use exception notes
+(:pep:`678`).
+
+Custom Timestamp Formats
+-------------------------
+
+Making the timestamp format string customizable beyond the predefined
+``us``/``ns``/``iso`` options was considered and rejected in favor of
+simplicity.  The three built-in formats cover the common needs: human-readable
+with microsecond precision, raw nanoseconds for programmatic use, and ISO 8601
+for correlation with external systems.
+
+Configurable Control Flow Exception Set
+-----------------------------------------
+
+Making the set of timestamp-excluded control flow exceptions configurable was
+considered and rejected.  The exclusion check is in the hot path of exception
+creation and must use C type pointer identity comparison to be fast enough.
+Supporting a user-configurable set would require either an isinstance check
+(too slow, as it walks the class hierarchy) or maintaining a hash set of type
+pointers (added complexity with unclear benefit).  The hard-coded exclusion of
+``StopIteration`` and ``StopAsyncIteration`` is sufficient: these are the only
+exceptions used pervasively for control flow at frequencies where a
+``clock_gettime`` call would be measurable.
 
 Millisecond Precision
 ---------------------
@@ -417,46 +474,7 @@ nanosecond precision was chosen to:
 Open Issues
 ===========
 
-1. Should there be a Python API to programmatically enable/disable timestamps
-   at runtime?
-
-2. Should there be a way to retroactively add timestamps to existing exception
-   objects?
-
-3. Should the timestamp format be customizable beyond the predefined options?
-
-4. **Always collecting timestamps vs. conditional collection**: Performance testing
-   shows that collecting timestamps at exception instantiation time is cheap enough
-   to do unconditionally. If we always collect them:
-
-   - The ``__timestamp_ns__`` attribute would always exist, simplifying the
-     implementation and making the pickle code cleaner (though pickled exceptions
-     would be slightly larger)
-   - Exceptions will unpickle cleanly on older Python versions (they'll just have
-     an extra attribute that older versions ignore)
-   - However, we don't currently have extensive testing for cross-version pickle
-     compatibility of exceptions with new attributes. Should we add such tests?
-     Is this level of compatibility testing necessary?
-
-5. **Control flow exception handling**: The current implementation does not collect
-   timestamps for ``StopIteration`` and ``AsyncStopIteration`` to avoid performance
-   impact on normal control flow. However, other projects use custom exceptions for
-   control flow (e.g., Sphinx's ``Skip`` exception), requiring configurability.
-
-   Key challenges:
-
-   - **API Design**: What's the best way to allow projects to register their
-     control-flow exceptions? Environment variable? Python API? Both?
-   - **Performance**: The check is in the hot path of exception creation and must
-     be extremely fast. How can we make this configurable without impacting
-     performance for the common case?
-   - **Subclass handling**: Should exclusions apply to subclasses? This adds
-     complexity and performance overhead.
-   - **Default set**: Should we expand the default exclusion list beyond
-     ``StopIteration`` and ``AsyncStopIteration``?
-
-   This needs careful API design and performance testing before committing to
-   a specific approach.
+None at this time.
 
 
 Acknowledgements