Skip to content

PEP 9999: Add timestamps to exception tracebacks #4592

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
gpshead wants to merge 4 commits into
base: main
Choose a base branch
from
Draft

PEP 9999: Add timestamps to exception tracebacks #4592

Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
aa4f6dc
PEP-8XX: Add timestamps to exception tracebacks
gpshead Sep 17, 2025
5a25936
Add open issues about timestamp collection and control flow exceptions
gpshead Sep 17, 2025
47d0b78
Expand motivation with answers to common questions
gpshead Sep 18, 2025
892bb05
Update control flow exception handling to acknowledge configurability…
gpshead Sep 18, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Update control flow exception handling to acknowledge configurability… 
… need

Based on feedback from @picnixz about Sphinx's Skip exception and other
projects using exceptions for control flow:

1. Renamed "Special Cases" to "Control Flow Exceptions" for clarity
2. Added acknowledgment that other projects need this configurability
3. Deferred specific API design to open issues
4. Updated Open Issue #5 with key challenges:
   - API design options (env var vs Python API)
   - Performance constraints in the hot path
   - Subclass handling complexity
   - Whether to expand the default exclusion list

The PEP now acknowledges the need for configurability while leaving the
specific implementation approach as an open question requiring careful
API design and performance testing.

🤖 Generated with Claude Code (https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>
  • Loading branch information
@gpshead @claude
gpshead and claude committed Sep 18, 2025
commit 892bb0525a38bacbae48cba0c45990018c009315
38 changes: 25 additions & 13 deletions peps/pep-08XX.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -241,17 +241,21 @@ class. This attribute will store the time in nanoseconds since the Unix epoch
- The timestamp represents when the exception object was created, which is
typically when it was raised

Special Cases
-------------
Control Flow Exceptions
------------------------

To avoid performance impacts on normal control flow, timestamps will **not** be
collected for the following exception types even when the feature is enabled:
collected for certain exception types even when the feature is enabled. By default:

- ``StopIteration``
- ``AsyncStopIteration``

These exceptions are frequently used for control flow in iterators and async
iterators, and adding timestamps would introduce unnecessary overhead.
iterators. However, other projects also use custom exceptions for control flow
(e.g., Sphinx's ``Skip`` exception), making the need for configurability clear.

The current implementation hard-codes these two exceptions for performance
reasons. See Open Issues for discussion about making this configurable.

Configuration
-------------
Expand Down Expand Up @@ -436,15 +440,23 @@ Open Issues

5. **Control flow exception handling**: The current implementation does not collect
timestamps for ``StopIteration`` and ``AsyncStopIteration`` to avoid performance
impact on normal control flow. Several questions arise:

- Should this exclusion be configurable at runtime?
- Should it apply to subclasses of these exceptions?
- The check for these specific exceptions is in the hot path of exception
creation and must be extremely fast. The current implementation uses a simple
type check for performance. Adding complexity like subclass checks or a
configurable tuple of excluded exceptions would impact performance. Is the
current simple approach acceptable?
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.


Acknowledgements
Expand Down
Loading