Module-level docstrings follow exactly the same guidelines but without the
blank line between the summary and the details.
-
-
-Exception Handling
-------------------
-
-Avoid finally: blocks in favor of explict catches because a throw
-from a finally block will lose any pending exception. An explicit
-catch can chain it (see below).
-
-To behave similarly under Python 2 and 3, use add_ex_tb() to
-explicitly add stack traces to any exceptions that are going to be
-re-raised by anything other than a no-argument raise (otherwise the
-stack trace will be lost)::
-
-
- try:
- ...
- except ... as ex:
- add_ex_tb(ex)
- pending_ex = ex
- ...
- raise pending_ex
-
-If 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 This can be accomplished via
-``add_ex_ctx()``::
-
- try:
- ...
- except ... as ex:
- add_ex_tb(ex)
- try:
- ...
- except ... as ex2:
- add_ex_tb(ex2)
- raise add_ex_ctx(ex2, ex)
-
-See the end of ``lib/bup/compat.py`` for a functional example.