hooke/playlist.py

   1 # Copyright (C) 2010 W. Trevor King <wking@drexel.edu>
   2 #
   3 # This file is part of Hooke.
   4 #
   5 # Hooke is free software: you can redistribute it and/or
   6 # modify it under the terms of the GNU Lesser General Public
   7 # License as published by the Free Software Foundation, either
   8 # version 3 of the License, or (at your option) any later version.
   9 #
  10 # Hooke is distributed in the hope that it will be useful,
  11 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  12 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13 # GNU Lesser General Public License for more details.
  14 #
  15 # You should have received a copy of the GNU Lesser General Public
  16 # License along with Hooke.  If not, see
  17 # <http://www.gnu.org/licenses/>.
  18
  19 """The `playlist` module provides a :class:`Playlist` and its subclass
  20 :class:`FilePlaylist` for manipulating lists of
  21 :class:`hooke.curve.Curve`\s.
  22 """
  23
  24 import copy
  25 import hashlib
  26 import os.path
  27 import xml.dom.minidom
  28
  29 from . import curve as curve
  30 from .compat import minidom as minidom  # dynamically patch xml.sax.minidom
  31
  32
  33 class NoteIndexList (list):
  34     """A list that keeps track of a "current" item and additional notes.
  35
  36     :attr:`index` (i.e. "bookmark") is the index of the currently
  37     current curve.  Also keep a :class:`dict` of additional information
  38     (:attr:`info`).
  39     """
  40     def __init__(self, name=None):
  41         super(NoteIndexList, self).__init__()
  42         self.name = name
  43         self.info = {}
  44         self._index = 0
  45
  46     def __str__(self):
  47         return '<%s %s>' % (self.__class__.__name__, self.name)
  48
  49     def _setup_item(self, item):
  50         """Perform any required initialization before returning an item.
  51         """
  52         pass
  53
  54     def current(self):
  55         if len(self) == 0:
  56             return None
  57         item = self[self._index]
  58         self._setup_item(item)
  59         return item
  60
  61     def jump(self, index):
  62         if len(self) == 0:
  63             self._index = 0
  64         else:
  65             self._index = index % len(self)
  66
  67     def next(self):
  68         self.jump(self._index + 1)
  69
  70     def previous(self):
  71         self.jump(self._index - 1)
  72
  73     def filter(self, keeper_fn=lambda item:True, *args, **kwargs):
  74         c = copy.deepcopy(self)
  75         for item in reversed(c):
  76             c._setup_item(item)
  77             if keeper_fn(item, *args, **kwargs) != True:
  78                 c.remove(item)
  79         try: # attempt to maintain the same current item
  80             c._index = c.index(self.current())
  81         except ValueError:
  82             c._index = 0
  83         return c
  84
  85 class Playlist (NoteIndexList):
  86     """A :class:`NoteIndexList` of :class:`hooke.curve.Curve`\s.
  87
  88     Keeps a list of :attr:`drivers` for loading curves.
  89     """
  90     def __init__(self, drivers, name=None):
  91         super(Playlist, self).__init__(name=name)
  92         self.drivers = drivers
  93         self._loaded = [] # List of loaded curves, see :meth:`._setup_item`.
  94         self._max_loaded = 100 # curves to hold in memory simultaneously.
  95
  96     def append_curve_by_path(self, path, info=None, identify=True):
  97         if self.path != None:
  98             path = os.path.join(os.path.dirname(self.path), path)
  99         path = os.path.normpath(path)
 100         c = curve.Curve(path, info=info)
 101         if identify == True:
 102             c.identify(self.drivers)
 103         self.append(c)
 104         return c
 105
 106     def _setup_item(self, curve):
 107         if curve != None and curve not in self._loaded:
 108             if curve not in self:
 109                 self.append(curve)
 110             if curve.driver == None:
 111                 c.identify(self.drivers)
 112             if curve.data == None:
 113                 curve.load()
 114             self._loaded.append(curve)
 115             if len(self._loaded) > self._max_loaded:
 116                 oldest = self._loaded.pop(0)
 117                 oldest.unload()
 118
 119 class FilePlaylist (Playlist):
 120     version = '0.1'
 121
 122     def __init__(self, drivers, name=None, path=None):
 123         super(FilePlaylist, self).__init__(drivers, name)
 124         self.set_path(path)
 125         self._digest = None
 126         self._ignored_keys = [
 127             'experiment',  # class instance, not very exciting.
 128             ]
 129
 130     def set_path(self, path):
 131         if path != None:
 132             if not path.endswith('.hkp'):
 133                 path += '.hkp'
 134             self.path = path
 135             if self.name == None:
 136                 self.name = os.path.basename(path)
 137
 138     def is_saved(self):
 139         return self.digest() == self._digest
 140
 141     def digest(self):
 142         r"""Compute the sha1 digest of the flattened playlist
 143         representation.
 144
 145         Examples
 146         --------
 147
 148         >>> root_path = os.path.sep + 'path'
 149         >>> p = FilePlaylist(drivers=[],
 150         ...                  path=os.path.join(root_path, 'to','playlist'))
 151         >>> p.info['note'] = 'An example playlist'
 152         >>> c = curve.Curve(os.path.join(root_path, 'to', 'curve', 'one'))
 153         >>> c.info['note'] = 'The first curve'
 154         >>> p.append(c)
 155         >>> c = curve.Curve(os.path.join(root_path, 'to', 'curve', 'two'))
 156         >>> c.info['note'] = 'The second curve'
 157         >>> p.append(c)
 158         >>> p.digest()
 159         '\\\x14\x87\x88*q\xf8\xaa\xa7\x84f\x82\xa1S>\xfd3+\xd0o'
 160         """
 161         string = self.flatten()
 162         return hashlib.sha1(string).digest()
 163
 164     def flatten(self, absolute_paths=False):
 165         """Create a string representation of the playlist.
 166
 167         A playlist is an XML document with the following syntax::
 168
 169             <?xml version="1.0" encoding="utf-8"?>
 170             <playlist attribute="value">
 171               <curve path="/my/file/path/"/ attribute="value" ...>
 172               <curve path="...">
 173             </playlist>
 174
 175         Relative paths are interpreted relative to the location of the
 176         playlist file.
 177
 178         Examples
 179         --------
 180
 181         >>> root_path = os.path.sep + 'path'
 182         >>> p = FilePlaylist(drivers=[],
 183         ...                  path=os.path.join(root_path, 'to','playlist'))
 184         >>> p.info['note'] = 'An example playlist'
 185         >>> c = curve.Curve(os.path.join(root_path, 'to', 'curve', 'one'))
 186         >>> c.info['note'] = 'The first curve'
 187         >>> p.append(c)
 188         >>> c = curve.Curve(os.path.join(root_path, 'to', 'curve', 'two'))
 189         >>> c.info['note'] = 'The second curve\\nwith endlines'
 190         >>> p.append(c)
 191         >>> print p.flatten() # doctest: +NORMALIZE_WHITESPACE +REPORT_UDIFF
 192         <?xml version="1.0" encoding="utf-8"?>
 193         <playlist index="0" note="An example playlist" version="0.1">
 194            <curve note="The first curve" path="curve/one"/>
 195            <curve note="The second curve&#xA;with endlines" path="curve/two"/>
 196         </playlist>
 197         <BLANKLINE>
 198         >>> print p.flatten(absolute_paths=True) # doctest: +NORMALIZE_WHITESPACE +REPORT_UDIFF
 199         <?xml version="1.0" encoding="utf-8"?>
 200         <playlist index="0" note="An example playlist" version="0.1">
 201            <curve note="The first curve" path="/path/to/curve/one"/>
 202            <curve note="The second curve&#xA;with endlines" path="/path/to/curve/two"/>
 203         </playlist>
 204         <BLANKLINE>
 205         """
 206         implementation = xml.dom.minidom.getDOMImplementation()
 207         # create the document DOM object and the root element
 208         doc = implementation.createDocument(None, 'playlist', None)
 209         root = doc.documentElement
 210         root.setAttribute('version', self.version) # store playlist version
 211         root.setAttribute('index', str(self._index))
 212         for key,value in self.info.items(): # save info variables
 213             root.setAttribute(key, str(value))
 214         for curve in self: # save curves and their attributes
 215             curve_element = doc.createElement('curve')
 216             root.appendChild(curve_element)
 217             path = os.path.abspath(os.path.expanduser(curve.path))
 218             if absolute_paths == False:
 219                 path = os.path.relpath(
 220                     path,
 221                     os.path.dirname(
 222                         os.path.abspath(
 223                             os.path.expanduser(self.path))))
 224             curve_element.setAttribute('path', path)
 225             for key,value in curve.info.items():
 226                 if key in self._ignored_keys:
 227                     continue
 228                 curve_element.setAttribute(key,str(value))
 229         string = doc.toprettyxml(encoding='utf-8')
 230         root.unlink() # break circular references for garbage collection
 231         return string
 232
 233     def _from_xml_doc(self, doc, identify=True):
 234         """Load a playlist from an :class:`xml.dom.minidom.Document`
 235         instance.
 236         """
 237         root = doc.documentElement
 238         for attribute,value in root.attributes.items():
 239             if attribute == 'version':
 240                 assert value == self.version, \
 241                     'Cannot read v%s playlist with a v%s reader' \
 242                     % (value, self.version)
 243             elif attribute == 'index':
 244                 self._index = int(value)
 245             else:
 246                 self.info[attribute] = value
 247         for curve_element in doc.getElementsByTagName('curve'):
 248             path = curve_element.getAttribute('path')
 249             info = dict(curve_element.attributes.items())
 250             info.pop('path')
 251             self.append_curve_by_path(path, info, identify=identify)
 252         self.jump(self._index) # ensure valid index
 253
 254     def from_string(self, string, identify=True):
 255         """Load a playlist from a string.
 256
 257         Examples
 258         --------
 259
 260         >>> string = '''<?xml version="1.0" encoding="utf-8"?>
 261         ... <playlist index="1" note="An example playlist" version="0.1">
 262         ...     <curve note="The first curve" path="../curve/one"/>
 263         ...     <curve note="The second curve&#xA;with endlines" path="../curve/two"/>
 264         ... </playlist>
 265         ... '''
 266         >>> p = FilePlaylist(drivers=[],
 267         ...                  path=os.path.join('path', 'to', 'my', 'playlist'))
 268         >>> p.from_string(string, identify=False)
 269         >>> p._index
 270         1
 271         >>> p.info
 272         {u'note': u'An example playlist'}
 273         >>> for curve in p:
 274         ...     print curve.path
 275         path/to/curve/one
 276         path/to/curve/two
 277         >>> p[-1].info['note']
 278         u'The second curve\\nwith endlines'
 279         """
 280         doc = xml.dom.minidom.parseString(string)
 281         self._from_xml_doc(doc, identify=identify)
 282
 283     def load(self, path=None, identify=True):
 284         """Load a playlist from a file.
 285         """
 286         self.set_path(path)
 287         doc = xml.dom.minidom.parse(self.path)
 288         self._from_xml_doc(doc, identify=identify)
 289         self._digest = self.digest()
 290
 291     def save(self, path=None):
 292         """Saves the playlist in a XML file.
 293         """
 294         self.set_path(path)
 295         f = file(self.path, 'w')
 296         f.write(self.flatten())
 297         f.close()