From 277b7a89f10a5cfa8b216db77d0d522d1fe8fc94 Mon Sep 17 00:00:00 2001 From: Blake Griffith Date: Tue, 5 Jul 2016 21:59:00 -0500 Subject: [PATCH] Update ErrorHandler docstring. --- certbot/error_handler.py | 25 ++++++++++++++++--------- 1 file changed, 16 insertions(+), 9 deletions(-) diff --git a/certbot/error_handler.py b/certbot/error_handler.py index 10e956e13..f3226de9d 100644 --- a/certbot/error_handler.py +++ b/certbot/error_handler.py @@ -21,19 +21,26 @@ _SIGNALS = ([signal.SIGTERM] if os.name == "nt" else class ErrorHandler(object): - """Registers functions to be called if an exception or signal occurs. + """Context manager for running code that must be cleaned up on failure. - This class allows you to register functions that will be called when - an exception (excluding SystemExit) or signal is encountered. The - class works best as a context manager. For example: + The context manager allows you to register functions that will be called + when an exception (excluding SystemExit) or signal is encountered. Usage: - with ErrorHandler(cleanup_func): + handler = ErrorHandler(cleanup1_func, *cleanup1_args, **cleanup1_kwargs) + handler.register(cleanup2_func, *cleanup2_args, **cleanup2_kwargs) + + with handler: do_something() - If an exception is raised out of do_something, cleanup_func will be - called. The exception is not caught by the ErrorHandler. Similarly, - if a signal is encountered, cleanup_func is called followed by the - previously registered signal handler. + Or for one cleanup function: + + with ErrorHandler(func, args, kwargs): + do_something() + + If an exception is raised out of do_something, the cleanup functions will + be called in last in first out order. Then the exception is raised. + Similarly, if a signal is encountered, the cleanup functions are called + followed by the previously received signal handler. Each registered cleanup function is called exactly once. If a registered function raises an exception, it is logged and the next function is called.