root/trunk/RBFoundation/RBFoundation/Utilities.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
##~
##~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

"""Just a handy sub-tool set of tools.  They just clean up the code a bit more..."""

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

from __future__ import generators
import types

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

_collectiontypes = (list, tuple, types.GeneratorType)

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

def isIterable(item):
    if isinstance(item, _collectiontypes):
        return True
    elif hasattr(item, '__iter__'):
        return True
    else:
        return False

def asIterable(item):
    if isinstance(item, _collectiontypes):
        return item
    elif hasattr(item, '__iter__'):
        return item
    else: 
        return [item]

def irip(collection):
    collection = map(iter, collection)
    try:
        while collection:
            section = []
            for coll in collection:
                section.append(coll.next())
            yield section
    except StopIteration:
        pass

def rip(collection):
    return list(irip(collection))

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

def flatten(collection, level=1):
    if isinstance(collection, (list, tuple)):
        if level:
            return [each for item in collection for each in flatten(item, level-1)]
        else:
            return collection
    else:
        return [collection]

def flattenall(collection):
    return flatten(collection, -1)

def cleanupstrlst(datalst, FilterResult=0):
    """Strips characters from a list of strings, and drops subsequent empty strings.

    >>> cleanupstrlst(["   this  ", "  is  ", " \\t fun \\t \\r", "  \\n \\r \\t test\\t\\t"])
    ['this', 'is', 'fun', 'test']
    """
    result = map(str.strip, datalst)
    if FilterResult:
        return filter(None, result)
    else: return result

def joinclean(joinstr, data, *args, **kw):
    """Uses cleanupstrlst, then joins the result using joinstr.
    If data is simply a string, then the data is splitup using strtolist.

    >>> joinclean(".", ["   this  ", "  is  ", " \\t fun \\t \\r", "  \\n \\r \\t test\\t\\t"])
    'this.is.fun.test'
    >>> joinclean("-", "data, , fun  ,   data   ,   oh\\t\\t\\t ,please  \\t, \\r\\n can \\t  ,  I have more data!   ")
    'data--fun-data-oh-please-can-I have more data!'

    """
    if isinstance(data, list):
        return joinstr.join(cleanupstrlst(data, *args, **kw))
    elif isinstance(data, (str, unicode)):
        return joinstr.join(strtolist(data, *args, **kw))

def strtolist(data, splitchar=',', *args, **kw):
    """Splits a dilimited string, then runs the result through cleanupstrlst.

    >>> strtolist("data, , fun  ,   data   ,   oh\\t\\t\\t ,please  \\t, \\r\\n can \\t  ,  I have more data!   ")
    ['data', '', 'fun', 'data', 'oh', 'please', 'can', 'I have more data!']
    """

    return cleanupstrlst(data.split(splitchar), *args, **kw)

#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
#~ Tree Iteration/Searching
#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

class TreeDict(dict):
    def addleaf(self, leaf):
        self[None] = leaf
    def addbranch(self, key, branch):
        self[key] = branch

class TreeIterator(object):
    TreeFactory = TreeDict

    def __init__(self, root=()):
        self.SetRoot(root)

    def GetRoot(self, root):
        return self._root
    def SetRoot(self, root):
        self._root = root

    def isBranch(self, key, value):
        return bool(key)

    def asTree(self):
        resulttree = self.TreeFactory()
        workqueue = [(resulttree, self._GetRootAsIter())]
        while workqueue:
            tree, itemcollection = workqueue.pop()
            for key, item in itemcollection:
                if self.isBranch(key, item):
                    try: 
                        itemtree=tree[key]
                    except LookupError:
                        itemtree=self.TreeFactory()
                        tree.addbranch(key, itemtree)
                    workqueue.append((itemtree, item))
                else:
                    tree.addleaf(item)
        return resulttree

    def iterByDepth(self, noDuplicates=False, yieldkeys=False):
        iterResult = self._iter(yieldkeys, -1)
        if noDuplicates:
            return self.iterFilterDuplicates(iterResult, yieldkeys)
        else:
            return iterResult

    def iterByBreadth(self, noDuplicates=False, yieldkeys=False):
        iterResult = self._iter(yieldkeys, 0)
        if noDuplicates:
            return self.iterFilterDuplicates(iterResult, yieldkeys)
        else:
            return iterResult

    def iterFilterDuplicates(self, iterable, resultDecorated=False):
        if resultDecorated:
            getvalue = lambda x:x[-1]
        else: 
            getvalue = lambda x:x

        allresults = {}
        for item in iterable:
            value = getvalue(item)
            if value not in allresults:
                allresults[value]=None
                yield item

    def _GetRootAsIter(self):
        if callable(self._root):
            return self._root()
        else:
            return iter(self._root)

    def _iter(self, yieldkeys=False, popindex=-1):
        workqueue = [((), self._GetRootAsIter())]
        while workqueue:
            path, itemcollection = workqueue.pop(popindex)
            tempqueue = []
            for key, item in itemcollection:
                newkey = path+(key,)
                if self.isBranch(key, item):
                    tempqueue.append((newkey, item))
                elif yieldkeys:
                    yield newkey, item
                else:
                    yield item
            if popindex<0:
                tempqueue.reverse()
            workqueue.extend(tempqueue)

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

if __name__=='__main__':
    print "Testing..."
    import doctest, Utilities
    doctest.testmod(Utilities)
    print "Test complete."