root/trunk/RBFoundation/RBFoundation/TaskProgress.py

#!/usr/bin/env python
##~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
##~ License 
##~ 
##- The RuneBlade Foundation library is intended to ease some 
##- aspects of writing intricate Jabber, XML, and User Interface (wxPython, etc.) 
##- applications, while providing the flexibility to modularly change the 
##- architecture. Enjoy.
##~ 
##~ Copyright (C) 2002  TechGame Networks, LLC.
##~ 
##~ This library is free software; you can redistribute it and/or
##~ modify it under the terms of the BSD style License as found in the 
##~ LICENSE file included with this distribution.
##~ 
##~ TechGame Networks, LLC can be reached at:
##~ 3578 E. Hartsel Drive #211
##~ Colorado Springs, Colorado, USA, 80920
##~
##~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
#~ Imports 
#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

from SubObs.Basic import Subject

#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
#~ Definitions 
#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

def SimpleSubtaskSum(self, Task):
    """Just an oversimplifed way to Rollup subtask progress."""
    result = 0.
    for subtask in Task.Subtasks:
        result += subtask.Percentage
    Task.Progress = result

#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

class TaskProgress(object):
    """Class to encapsulate recursive subtasks in a reasonable way for overal progress updates."""

    #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    #~ Constants / Variables / Etc. 
    #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    SubjectFactory = Subject
    SubtaskFactory = None
    RollupStrategy = SimpleSubtaskSum

    ProgressStart = 0
    ProgressEnd = 1
    ProgressUpdateSteps = 0
    ProgressUpdateThreshold = 0
    _Progress = 0

    #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    #~ Definitions 
    #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    def __init__(self, name, *args, **kw):
        self.Name = name
        self.OnProgress = self.SubjectFactory()
        self.OnAddSubtask = self.SubjectFactory()
        if args or kw:
            self.SetProgressRange(*args, **kw)

    def __iadd__(self, DeltaProgress):
        self.Progress += DeltaProgress
        return self
    def __isub__(self, DeltaProgress):
        self.Progress -= DeltaProgress
        return self

    def NewSubtask(self, Name, Start=0., Stop=1., UpdateSteps=None):
        subtask = self.SubtaskFactory(Name, Start, Stop, UpdateSteps or self.ProgressUpdateSteps)
        return self.AddSubtask(subtask)

    def AddSubtask(self, subtask):
        try: 
            self.Subtasks.append(subtask)
        except AttributeError: 
            self.Subtasks = [subtask]
        subtask.OnProgress.Add(self._OnSubtaskUpdate)
        self.OnAddSubtask.Update(self, subtask)
        self._OnSubtaskUpdate(subtask, subtask.Progress)
        return subtask

    #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    #~ Properties
    #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    def SetProgressRange(self, Start, Stop, UpdateSteps=10, bSetProgress=1):
        self.ProgressUpdateSteps = UpdateSteps
        self.ProgressUpdateThreshold = Start
        self.ProgressStart = Start
        self.ProgressEnd = Stop
        if bSetProgress: 
            self.Progress = Start
        else:
            self.OnProgress.Update(self, self.Progress)

    def ResetProgress(self):
        self.ProgressUpdateThreshold = self.ProgressStart
        self.Progress = self.ProgressStart

    def _getProgress(self):
        return self._Progress
    def _setProgress(self, Progress):
        self._Progress = Progress
        if Progress >= self.ProgressUpdateThreshold:
            self.OnProgress.Update(self, Progress)
            self.ProgressUpdateThreshold += float(self.ProgressEnd - self.ProgressStart) / self.ProgressUpdateSteps
        elif Progress >= self.ProgressEnd:
            self.OnProgress.Update(self, Progress)
    def _delProgress(self):
        del self._Progress
    Progress = property(_getProgress, _setProgress, _delProgress, doc="The tasks progress in real numbers.")

    def _getPercent(self):
        result = (self._Progress - self.ProgressStart) / float(self.ProgressEnd - self.ProgressStart)
        return max(0., min(1., result))
    def _setPercent(self, percent):
        self.Progress = self.ProgressStart + percent*(self.ProgressEnd-self.ProgressStart)
    Percentage = Percent = property(_getPercent, _setPercent, _delProgress, doc="The task's percent [0.,1.] complete.  Linear mapping of Progress to the progress range.")

    #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    #~ Protected Methods 
    #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    def _OnSubtaskUpdate(self, subtask, Progress):
        self.RollupStrategy(self)

TaskProgress.SubtaskFactory = TaskProgress

#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
#~ Testing 
#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

if __name__=='__main__':
    print "Testing..."

    task = TaskProgress('Test task', 0, 10000, 15)

    task += 10
    print task.Progress, task.ProgressStart, task.ProgressEnd, task.ProgressUpdateSteps

    def PrintProgress(task, progress):
        print '%-20s [%5.1f%%]' % (task.Name, task.Percentage * 100)

    task.OnProgress.Add(PrintProgress)

    print
    print "==", "Task progress", "="*20
    for p in range(task.ProgressStart, task.ProgressEnd, (task.ProgressEnd - task.ProgressStart)/task.ProgressUpdateSteps * .4):
        task.Progress = p
    task.Progress = task.ProgressEnd

    print
    print "==", "Subtasks", "="*20
    task.SetProgressRange(0.,1.,5)
    for each in xrange(5): 
        subtask = task.NewSubtask('   Subtask %s' % each, 0., 1., 4)
        subtask.OnProgress.Add(PrintProgress)

    while task.Percent < 1.:
        for subtask in task.Subtasks:
            subtask += 0.01

    print "Test complete."