re-raised by anything other than a no-argument raise (otherwise the
stack trace will be lost)::
-
try:
...
except ... as ex:
...
raise pending_ex
-If an exception is thrown from an exception handler, the pending
-exception should be "chained" to the new exception as the context.
-This can be accomplished via ``chain_ex()``::
+When an exception is thrown from an exception handler, the pending
+exception should be the `"context"
+<https://docs.python.org/3/reference/simple_stmts.html#the-raise-statement>`_
+of the new exception, which can be accomplished (portably) via
+``pending_raise()``::
+
+ try:
+ ...
+ except ... as ex:
+ with pending_raise(ex):
+ clean_up()
+
+This should do roughly the same thing in Python 2 and Python 3,
+throwing any exception from ``clean_up()`` after adding ex as the
+``__context__`` if clean_up() throws, and throwing ``ex`` otherwise.
+
+If for some reason, you need more control, you can use
+``add_ex_ctx()`` directly::
try:
...
...
except ... as ex2:
add_ex_tb(ex2)
- raise chain_ex(ex2, ex)
+ raise add_ex_ctx(ex2, ex)
+ raise
-See the end of ``lib/bup/compat.py`` for a functional example.
+See the end of ``lib/bup/compat.py`` for a functional example, and all
+of this can be removed once we drop support for Python 2.