From e49af1998c2e4c6d6114dee551b51a514f7dfa71 Mon Sep 17 00:00:00 2001
From: Vassilii Khachaturov <vassilii@tarunz.org>
Date: Fri, 13 Sep 2013 08:08:15 +0000
Subject: [PATCH] 7061: docstring update

svn: r23107
---
 gramps/gen/user.py | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/gramps/gen/user.py b/gramps/gen/user.py
index cb6975bb1..e3cd4e4ab 100644
--- a/gramps/gen/user.py
+++ b/gramps/gen/user.py
@@ -80,8 +80,33 @@ class User():
     def end_progress(self):
         """
         Stop showing the progress indicator to the user.
+
+        Don't use this method directly, use progress instead.
         """
         pass
+
+    # Context-manager wrapper of the begin/step/end_progress above
+    @contextmanager
+    def progress(self, *args, **kwargs):
+        """
+        Preferred form of progress reporting.
+
+        Parameters: same as for begin_progress.
+        
+        Usage example (see gramps/cli/test/user_test.py):
+            with self.user.progress("Foo", "Bar", 0) as step:
+                for i in range(10):
+                    step()
+
+        Ensures end_progress will be called even if an exception was thrown.
+        """
+        self.begin_progress(*args, **kwargs)
+        try:
+            yield self.step_progress
+        except:
+            raise
+        finally:
+            self.end_progress()
     
     def prompt(self, title, message, accept_label, reject_label):
         """