more on run management

git-svn-id: svn://svn.cy55.de/Zope3/src/cybertools/trunk@1708 fd906abe-77d9-0310-91a1-e0d9ade77398

tracking/README.txt

@@ -1,6 +1,6 @@
-====================================
-User tracking in the loops framework
-====================================
+=========================
+User/Interaction tracking
+=========================
 
   ($Id$)
 
@@ -92,10 +92,38 @@ We still have access to older runs.
 
 We can also retrieve a run object with the run's data.
 
-  >>> run = tracks.getRun(3)
-  >>> run
+  >>> tracks.getRun(runId=3)
   <Run 3, ..., ..., False>
 
+We can also use the taskId for retrieving a task's current run.
+
+  >>> tracks.getRun(taskId='a001')
+  <Run 3, ..., ..., False>
+
+When we stop a run explicitly it is marked as ``finished``.
+
+  >>> tracks.stopRun('a001')
+  3
+  >>> tracks.getRun(runId=3)
+  <Run 3, ..., ..., True>
+  >>> tracks.getRun(runId=3).finished
+  True
+
+Stopping a run removes it from the set of current runs, so the associated
+task hasn't got a current run any longer:
+
+  >>> tracks.getRun('a001') is None
+  True
+
+We can also mark earlier runs by stopping them.
+
+  >>> tracks.getRun(runId=2)
+  <Run 2, ..., ..., False>
+  >>> tracks.stopRun('a001', 2)
+  2
+  >>> tracks.getRun(runId=2)
+  <Run 2, ..., ..., True>
+
 
 Fin de partie
 =============

tracking/btree.py

@@ -80,27 +80,30 @@ class TrackingStorage(BTreeContainer):
         run.start = run.end = getTimeStamp()
         return runId
 
-    def stopRun(self, taskId, runId=0, finish=True):
-        currentRun = self.currentRuns.get(taskId)
-        runId = runId or currentRun
-        if runId and runId == currentRun:
-            del self.currentRuns[taskId]
-        run = self.getRun(runId)
+    def stopRun(self, taskId=None, runId=0, finish=True):
+        if taskId is not None:
+            currentRun = self.currentRuns.get(taskId)
+            runId = runId or currentRun
+            if runId and runId == currentRun:
+                del self.currentRuns[taskId]
+        run = self.getRun(runId=runId)
         if run is not None:
             run.end = getTimeStamp()
             run.finished = finish
             return runId
+        return 0
 
-    def getRun(self, runId=0, taskId=None):
+    def getRun(self, taskId=None, runId=0):
         if taskId and not runId:
             runId = self.currentRuns.get(taskId)
         if runId:
             return self.runs.get(runId)
+        return None
 
     def saveUserTrack(self, taskId, runId, userName, data, replace=False):
         if not runId:
             runId = self.currentRuns.get(taskId) or self.startRun(taskId)
-        run = self.getRun(runId)
+        run = self.getRun(runId=runId)
         if run is None:
             raise ValueError('Invalid run: %i.' % runId)
         run.end = getTimeStamp()

tracking/interfaces.py

@@ -54,17 +54,18 @@ class ITrackingStorage(Interface):
         """ Create a new run for the task given and return its id.
         """
 
-    def stopRun(taskId, runId=0, finish=True):
+    def stopRun(taskId=None, runId=0, finish=True):
         """ Stop/finish a run.
             If the runId is 0 use the task's current run.
             If the run is the task's current one remove it from the set
             of current runs.
             Set the run's ``finished`` flag to the value of the ``finish``
             argument.
-            Return the real runId.
+            Return the real runId; return 0 if there is no run for the
+            parameters given.
         """
 
-    def getRun(runId, taskId=None):
+    def getRun(taskId=None, runId=0):
         """ Return the run object identified by ``runId``. Return None
             if there is no corresponding run.
             If ``runId`` is 0 and a ``taskId`` is given return the