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