From: Alfredo Deza <alfredo@deza.pe>
Date: Fri, 9 Aug 2013 23:08:53 +0000 (-0700)
Subject: add a bit more docs to demonstrate handler usage in the decorator
X-Git-Tag: v1.2~4^2
X-Git-Url: http://git-server-git.apps.pok.os.sepia.ceph.com/?a=commitdiff_plain;h=bb00d39ce6185219ad07429cc2abe334f214c9c6;p=ceph-deploy.git

add a bit more docs to demonstrate handler usage in the decorator

Signed-off-by: Alfredo Deza <alfredo@deza.pe>
---

diff --git a/ceph_deploy/util/decorators.py b/ceph_deploy/util/decorators.py
index cc111e5..9faa978 100644
--- a/ceph_deploy/util/decorators.py
+++ b/ceph_deploy/util/decorators.py
@@ -55,6 +55,22 @@ def catches(catch=None, handler=None, exit=True):
         def bar():
             some_call()
             print "Success!"
+
+    If adding a handler, it should accept a single argument, which would be the
+    exception that was raised, it would look like::
+
+        def my_handler(exc):
+            print 'Handling exception %s' % str(exc)
+            raise SystemExit
+
+        @catches(KeyboardInterrupt, handler=my_handler)
+        def bar():
+            some_call()
+
+    Note that the handler needs to raise its SystemExit if it wants to halt
+    execution, otherwise the decorator would continue as a normal try/except
+    block.
+
     """
     catch = catch or Exception
     logger = logging.getLogger('ceph_deploy')