7061: User.progress

docstrings

svn: r23093

gramps/gen/user.py

@@ -43,6 +43,8 @@ class User():
         """
         Start showing a progress indicator to the user.
 
+        Don't use this method directly, use progress instead.
+        
         @param title: the title of the progress meter
         @type title: str
         @param message: the message associated with the progress meter
@@ -58,6 +60,8 @@ class User():
     def step_progress(self):
         """
         Advance the progress meter.
+
+        Don't use this method directly, use progress instead.
         """
         pass
     
@@ -82,12 +86,26 @@ 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 context 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