Rename chain_ex to add_ex_ctx to reflect upstream terminology

In the raise[1] docs Python uses chaining to refer to "from" (cause)
linkage, not implicit exception/finally (context) linkage, so adjust
our function name to match.  (Also preparation for compat code to
handle from linkage).

[1] https://docs.python.org/3/reference/simple_stmts.html#the-raise-statement.

Signed-off-by: Rob Browning <rlb@defaultvalue.org>

diff --git a/CODINGSTYLE b/CODINGSTYLE
index 1bc76fadfb09cfabc548cf0cc6e33387848f7030..0344157516773c0e1709fb07484c9e8b18408217 100644 (file)
--- a/CODINGSTYLE
+++ b/CODINGSTYLE
@@ -53,8 +53,10 @@ stack trace will be lost)::
   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()``::
+exception should be the `"context"
+<https://docs.python.org/3/reference/simple_stmts.html#the-raise-statement>`_
+of the new exception This can be accomplished via
+``add_ex_ctx()``::
 
   try:
       ...
@@ -64,6 +66,6 @@ This can be accomplished via ``chain_ex()``::
           ...
       except ... as ex2:
           add_ex_tb(ex2)
-          raise chain_ex(ex2, ex)
+          raise add_ex_ctx(ex2, ex)
 
 See the end of ``lib/bup/compat.py`` for a functional example.

diff --git a/lib/bup/compat.py b/lib/bup/compat.py
index 6f2e6d233dc532e882771ebf6fe3e1b26e2a86f0..e598853302d94a5f660388b737d6f15ccf09f275 100644 (file)
--- a/lib/bup/compat.py
+++ b/lib/bup/compat.py
@@ -4,7 +4,7 @@ from traceback import print_exception
 import sys
 
 # Please see CODINGSTYLE for important exception handling guidelines
-# and the rationale behind add_ex_tb(), chain_ex(), etc.
+# and the rationale behind add_ex_tb(), add_ex_ctx(), etc.
 
 py_maj = sys.version_info[0]
 py3 = py_maj >= 3
@@ -19,7 +19,7 @@ if py3:
         """Do nothing (already handled by Python 3 infrastructure)."""
         return ex
 
-    def chain_ex(ex, context_ex):
+    def add_ex_ctx(ex, context_ex):
         """Do nothing (already handled by Python 3 infrastructure)."""
         return ex
 
@@ -40,9 +40,9 @@ else:  # Python 2
             ex.__traceback__ = sys.exc_info()[2]
         return ex
 
-    def chain_ex(ex, context_ex):
-        """Chain context_ex to ex as the __context__ (unless it already has
-        one).  Return ex.
+    def add_ex_ctx(ex, context_ex):
+        """Make context_ex the __context__ of ex (unless it already has one).
+        Return ex.
 
         """
         if context_ex:
@@ -112,6 +112,6 @@ if __name__ == '__main__':
             try:
                 raise Exception('second')
             except Exception as ex2:
-                raise chain_ex(add_ex_tb(ex2), ex)
+                raise add_ex_ctx(add_ex_tb(ex2), ex)
 
     wrap_main(outer)

diff --git a/main.py b/main.py
index f955321d97afd80845d05be5d9d73c0c1caff023..ec86b2ac8376c7b4055d36db674b2edd544a531e 100755 (executable)
--- a/main.py
+++ b/main.py
@@ -42,7 +42,7 @@ os.environ['BUP_RESOURCE_PATH'] = resourcepath
 
 
 from bup import compat, helpers
-from bup.compat import add_ex_tb, chain_ex, wrap_main
+from bup.compat import add_ex_tb, add_ex_ctx, wrap_main
 from bup.helpers import atoi, columnate, debug1, log, tty_width
 
 
@@ -215,7 +215,7 @@ def filter_output(src_out, src_err, dest_out, dest_err):
                     if split[0]:
                         pending.setdefault(fd, []).extend(split)
     except BaseException as ex:
-        pending_ex = chain_ex(add_ex_tb(ex), pending_ex)
+        pending_ex = add_ex_ctx(add_ex_tb(ex), pending_ex)
     try:
         # Try to finish each of the streams
         for fd, pending_items in compat.items(pending):
@@ -223,9 +223,9 @@ def filter_output(src_out, src_err, dest_out, dest_err):
             try:
                 print_clean_line(dest, pending_items, width)
             except (EnvironmentError, EOFError) as ex:
-                pending_ex = chain_ex(add_ex_tb(ex), pending_ex)
+                pending_ex = add_ex_ctx(add_ex_tb(ex), pending_ex)
     except BaseException as ex:
-        pending_ex = chain_ex(add_ex_tb(ex), pending_ex)
+        pending_ex = add_ex_ctx(add_ex_tb(ex), pending_ex)
     if pending_ex:
         raise pending_ex
 
@@ -260,7 +260,7 @@ def run_subcmd(subcmd):
                 os.kill(p.pid, signal.SIGTERM)
                 p.wait()
         except BaseException as kill_ex:
-            raise chain_ex(add_ex_tb(kill_ex), ex)
+            raise add_ex_ctx(add_ex_tb(kill_ex), ex)
         raise ex
         
 wrap_main(lambda : run_subcmd(subcmd))