Commits

Anonymous committed 1835bb1

Adding TaskHandle.current_jobset()

  • Participants
  • Parent commits 8159a98

Comments (0)

Files changed (6)

File docs/library.txt

 
   changes = extractor.get_changes('extracted_variable')
 
-`changes` holds the changes this refactoring makes.  It is an instance
-of a subclass of `rope.base.change.Change`.
+`changes` holds the changes this refactoring makes.  Calculating it
+might be time consuming; See `rope.base.taskhandle.TaskHandle`_
+section for measuring its progress or interrupting it.
 
 
 Previewing And Performing Changes
 `rope.base.libutils.report_change()`.  That is, whenever you want to
 change a module you can do something like::
 
+  # Do the actual writing
   old_contents = read(path)
   write(path, new_content)
+
+  # Inform rope about the change
   libutils.report_change(myproject, path, old_contents)
 
+Where `read` and `write` stand for methods used for reading and
+writing files.
+
 
 Closing The Project
 -------------------
 `rope.base.taskhandle.TaskHandle`
 =================================
 
-For monitoring the progress and stopping time consuming tasks like
-some of refactorings.  `Project.do()` and `Refactoring.get_changes()`
-of some refactorings take a keyword argument called ``task_handle``.
-You can pass a `rope.base.taskhandle.TaskHandle` object as this
-argument.  See its methods for more information.
+Can be used for stopping and monitoring the progress of time consuming
+tasks like some of refactorings.  `Project.do()` and
+`Refactoring.get_changes()` of most refactorings take a keyword
+parameter called ``task_handle``.  You can pass a `TaskHandle` object
+to them.  A `TaskHandle` can be used for interrupting or observing a
+task.
+
+A task might consist of a few `JobSet`\s.  Each `JobSet` does a few
+jobs.  For instance calculating the changes for renaming a method in a
+class hierarchy has two job sets; We need to find the classes for
+constructing the class hierarchy and then we need to change the
+occurrences.
+
+The `TaskHandle.current_jobset()` returns the most recent `JobSet` or
+`None` if none has been started.  You can use the methods of `JobSet`
+for obtaining information about the current job.  So you might want to
+do something like::
+
+  import rope.base.taskhandle
+
+
+  handle = rope.base.taskhandle.TaskHandle("Test Task")
+
+  def update_progress():
+      jobset = handle.current_jobsets()
+      if jobset:
+          text = ''
+          if jobset.get_name() is not None:
+              text += jobset.get_name()
+          if jobset.get_active_job_name() is not None:
+              text += ' : ' + jobset.get_active_job_name()
+          percent = jobset.get_percent_done()
+          if percent is not None:
+              text = ' ... %s percent done' % percent
+          print text
+
+  handle.add_observer(update_progress)
+
+  changes = extractor.get_changes('extracted_variable', task_handle=handle)
 
 
 Refactorings

File rope/__init__.py

 """rope, a python refactoring library"""
 
 INFO = __doc__
-VERSION = '0.6m6'
+VERSION = '0.6'
 COPYRIGHT = """\
 Copyright (C) 2006-2007 Ali Gholami Rudi
 

File rope/base/taskhandle.py

 class TaskHandle(object):
 
     def __init__(self, name='Task', interrupts=True):
+        """Construct a TaskHandle
+
+        If `interrupts` is `False` the task won't be interrupted by
+        calling `TaskHandle.stop()`.
+
+        """
         self.name = name
         self.interrupts = interrupts
         self.stopped = False
         self.job_sets = []
         self.observers = []
 
-    def is_stopped(self):
-        return self.stopped
-
     def stop(self):
+        """Interrupts the refactoring"""
         if self.interrupts:
             self.stopped = True
             self._inform_observers()
 
-    def create_job_set(self, name='JobSet', count=None):
-        result = JobSet(self, name=name, count=count)
-        self.job_sets.append(result)
-        self._inform_observers()
-        return result
-
-    def get_job_sets(self):
-        return self.job_sets
+    def current_jobset(self):
+        """Return the current `JobSet`"""
+        if self.job_sets:
+            return self.job_sets[-1]
 
     def add_observer(self, observer):
         """Register an observer for this task handle
 
         The observer is notified whenever the task is stopped or
         a job gets finished.
+
         """
         self.observers.append(observer)
 
+    def is_stopped(self):
+        return self.stopped
+
+    def get_jobsets(self):
+        return self.job_sets
+
+    def create_jobset(self, name='JobSet', count=None):
+        result = JobSet(self, name=name, count=count)
+        self.job_sets.append(result)
+        self._inform_observers()
+        return result
+
     def _inform_observers(self):
         for observer in list(self.observers):
             observer()

File rope/refactor/rename.py

                                                    new_name))
         return changes
 
-    def _create_job_set(self, task_handle, count):
-        if task_handle is not None:
-            job_set = task_handle.create_job_set('Collecting Changes', count)
-        else:
-            job_set = rope.refactor.NullJobSet()
-        return job_set
-
     def _is_renaming_a_function_local_name(self):
         module, lineno = self.old_pyname.get_definition_location()
         if lineno is None:

File rope/ui/actionhelpers.py

         frame = Tkinter.Frame(toplevel)
         progress = rope.ui.uihelpers.ProgressBar(frame)
         def update_progress():
-            job_sets = handle.get_job_sets()
-            if job_sets:
-                job_set = job_sets[-1]
+            jobset = handle.current_jobset()
+            if jobset:
                 text = ''
-                if job_set.get_name() is not None:
-                    text += job_set.get_name()
-                if job_set.get_active_job_name() is not None:
-                    text += ' : ' + job_set.get_active_job_name()
+                if jobset.get_name() is not None:
+                    text += jobset.get_name()
+                if jobset.get_active_job_name() is not None:
+                    text += ' : ' + jobset.get_active_job_name()
                 progress.set_text(text)
-                percent = job_set.get_percent_done()
+                percent = jobset.get_percent_done()
                 if percent is not None:
                     progress.set_done_percent(percent)
         handle.add_observer(update_progress)

File ropetest/refactor/__init__.py

 
     def test_job_sets(self):
         handle = rope.base.taskhandle.TaskHandle()
-        jobs = handle.create_job_set()
-        self.assertEquals([jobs], handle.get_job_sets())
+        jobs = handle.create_jobset()
+        self.assertEquals([jobs], handle.get_jobsets())
 
     def test_starting_and_finishing_jobs(self):
         handle = rope.base.taskhandle.TaskHandle()
-        jobs = handle.create_job_set(name='test job set', count=1)
+        jobs = handle.create_jobset(name='test job set', count=1)
         jobs.started_job('job1')
         jobs.finished_job()
 
     @testutils.assert_raises(InterruptedTaskError)
     def test_test_checking_status(self):
         handle = rope.base.taskhandle.TaskHandle()
-        jobs = handle.create_job_set()
+        jobs = handle.create_jobset()
         handle.stop()
         jobs.check_status()
 
     @testutils.assert_raises(InterruptedTaskError)
     def test_test_checking_status_when_starting(self):
         handle = rope.base.taskhandle.TaskHandle()
-        jobs = handle.create_job_set()
+        jobs = handle.create_jobset()
         handle.stop()
         jobs.started_job('job1')
 
         handle = rope.base.taskhandle.TaskHandle()
         observer = _MockTaskObserver()
         handle.add_observer(observer)
-        jobs = handle.create_job_set()
+        jobs = handle.create_jobset()
         self.assertEquals(1, observer.called)
 
     def test_calling_the_observer_when_starting_and_finishing_jobs(self):
         handle = rope.base.taskhandle.TaskHandle()
         observer = _MockTaskObserver()
         handle.add_observer(observer)
-        jobs = handle.create_job_set(name='test job set', count=1)
+        jobs = handle.create_jobset(name='test job set', count=1)
         jobs.started_job('job1')
         jobs.finished_job()
         self.assertEquals(3, observer.called)
 
     def test_job_set_get_percent_done(self):
         handle = rope.base.taskhandle.TaskHandle()
-        jobs = handle.create_job_set(name='test job set', count=2)
+        jobs = handle.create_jobset(name='test job set', count=2)
         self.assertEquals(0, jobs.get_percent_done())
         jobs.started_job('job1')
         jobs.finished_job()
 
     def test_getting_job_name(self):
         handle = rope.base.taskhandle.TaskHandle()
-        jobs = handle.create_job_set(name='test job set', count=1)
+        jobs = handle.create_jobset(name='test job set', count=1)
         self.assertEquals('test job set', jobs.get_name())
         self.assertEquals(None, jobs.get_active_job_name())
         jobs.started_job('job1')