From 34f20329d71a77c14216129d6e9f49b78472b876 Mon Sep 17 00:00:00 2001
From: helmutm <helmutm@fd906abe-77d9-0310-91a1-e0d9ade77398>
Date: Tue, 1 May 2007 09:28:23 +0000
Subject: [PATCH] more on run management

git-svn-id: svn://svn.cy55.de/Zope3/src/cybertools/trunk@1708 fd906abe-77d9-0310-91a1-e0d9ade77398
---
 tracking/README.txt    | 38 +++++++++++++++++++++++++++++++++-----
 tracking/btree.py      | 19 +++++++++++--------
 tracking/interfaces.py |  7 ++++---
 3 files changed, 48 insertions(+), 16 deletions(-)

diff --git a/tracking/README.txt b/tracking/README.txt
index bec1e70..c5e23fa 100644
--- a/tracking/README.txt
+++ b/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
 =============
diff --git a/tracking/btree.py b/tracking/btree.py
index 6223c9b..fbd505b 100644
--- a/tracking/btree.py
+++ b/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()
diff --git a/tracking/interfaces.py b/tracking/interfaces.py
index b332ceb..8d0fd4a 100644
--- a/tracking/interfaces.py
+++ b/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