roundup/backends/back_anydbm.py

   1 #
   2 # Copyright (c) 2001 Bizar Software Pty Ltd (http://www.bizarsoftware.com.au/)
   3 # This module is free software, and you may redistribute it and/or modify
   4 # under the same terms as Python, so long as this copyright message and
   5 # disclaimer are retained in their original form.
   6 #
   7 # IN NO EVENT SHALL BIZAR SOFTWARE PTY LTD BE LIABLE TO ANY PARTY FOR
   8 # DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING
   9 # OUT OF THE USE OF THIS CODE, EVEN IF THE AUTHOR HAS BEEN ADVISED OF THE
  10 # POSSIBILITY OF SUCH DAMAGE.
  11 #
  12 # BIZAR SOFTWARE PTY LTD SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING,
  13 # BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
  14 # FOR A PARTICULAR PURPOSE.  THE CODE PROVIDED HEREUNDER IS ON AN "AS IS"
  15 # BASIS, AND THERE IS NO OBLIGATION WHATSOEVER TO PROVIDE MAINTENANCE,
  16 # SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
  17 #
  18 #$Id: back_anydbm.py,v 1.49 2002-07-18 11:41:10 richard Exp $
  19 '''
  20 This module defines a backend that saves the hyperdatabase in a database
  21 chosen by anydbm. It is guaranteed to always be available in python
  22 versions >2.1.1 (the dumbdbm fallback in 2.1.1 and earlier has several
  23 serious bugs, and is not available)
  24 '''
  25
  26 import whichdb, anydbm, os, marshal, re, weakref, string, copy
  27 from roundup import hyperdb, date, password, roundupdb
  28 from blobfiles import FileStorage
  29 from roundup.indexer import Indexer
  30 from locking import acquire_lock, release_lock
  31 from roundup.hyperdb import String, Password, Date, Interval, Link, \
  32     Multilink, DatabaseError, Boolean, Number
  33
  34 #
  35 # Now the database
  36 #
  37 class Database(FileStorage, hyperdb.Database, roundupdb.Database):
  38     """A database for storing records containing flexible data types.
  39
  40     Transaction stuff TODO:
  41         . check the timestamp of the class file and nuke the cache if it's
  42           modified. Do some sort of conflict checking on the dirty stuff.
  43         . perhaps detect write collisions (related to above)?
  44
  45     """
  46     def __init__(self, config, journaltag=None):
  47         """Open a hyperdatabase given a specifier to some storage.
  48
  49         The 'storagelocator' is obtained from config.DATABASE.
  50         The meaning of 'storagelocator' depends on the particular
  51         implementation of the hyperdatabase.  It could be a file name,
  52         a directory path, a socket descriptor for a connection to a
  53         database over the network, etc.
  54
  55         The 'journaltag' is a token that will be attached to the journal
  56         entries for any edits done on the database.  If 'journaltag' is
  57         None, the database is opened in read-only mode: the Class.create(),
  58         Class.set(), and Class.retire() methods are disabled.
  59         """
  60         self.config, self.journaltag = config, journaltag
  61         self.dir = config.DATABASE
  62         self.classes = {}
  63         self.cache = {}         # cache of nodes loaded or created
  64         self.dirtynodes = {}    # keep track of the dirty nodes by class
  65         self.newnodes = {}      # keep track of the new nodes by class
  66         self.transactions = []
  67         self.indexer = Indexer(self.dir)
  68         # ensure files are group readable and writable
  69         os.umask(0002)
  70
  71     def post_init(self):
  72         """Called once the schema initialisation has finished."""
  73         # reindex the db if necessary
  74         if self.indexer.should_reindex():
  75             self.reindex()
  76
  77     def reindex(self):
  78         for klass in self.classes.values():
  79             for nodeid in klass.list():
  80                 klass.index(nodeid)
  81         self.indexer.save_index()
  82
  83     def __repr__(self):
  84         return '<back_anydbm instance at %x>'%id(self)
  85
  86     #
  87     # Classes
  88     #
  89     def __getattr__(self, classname):
  90         """A convenient way of calling self.getclass(classname)."""
  91         if self.classes.has_key(classname):
  92             if __debug__:
  93                 print >>hyperdb.DEBUG, '__getattr__', (self, classname)
  94             return self.classes[classname]
  95         raise AttributeError, classname
  96
  97     def addclass(self, cl):
  98         if __debug__:
  99             print >>hyperdb.DEBUG, 'addclass', (self, cl)
 100         cn = cl.classname
 101         if self.classes.has_key(cn):
 102             raise ValueError, cn
 103         self.classes[cn] = cl
 104
 105     def getclasses(self):
 106         """Return a list of the names of all existing classes."""
 107         if __debug__:
 108             print >>hyperdb.DEBUG, 'getclasses', (self,)
 109         l = self.classes.keys()
 110         l.sort()
 111         return l
 112
 113     def getclass(self, classname):
 114         """Get the Class object representing a particular class.
 115
 116         If 'classname' is not a valid class name, a KeyError is raised.
 117         """
 118         if __debug__:
 119             print >>hyperdb.DEBUG, 'getclass', (self, classname)
 120         return self.classes[classname]
 121
 122     #
 123     # Class DBs
 124     #
 125     def clear(self):
 126         '''Delete all database contents
 127         '''
 128         if __debug__:
 129             print >>hyperdb.DEBUG, 'clear', (self,)
 130         for cn in self.classes.keys():
 131             for dummy in 'nodes', 'journals':
 132                 path = os.path.join(self.dir, 'journals.%s'%cn)
 133                 if os.path.exists(path):
 134                     os.remove(path)
 135                 elif os.path.exists(path+'.db'):    # dbm appends .db
 136                     os.remove(path+'.db')
 137
 138     def getclassdb(self, classname, mode='r'):
 139         ''' grab a connection to the class db that will be used for
 140             multiple actions
 141         '''
 142         if __debug__:
 143             print >>hyperdb.DEBUG, 'getclassdb', (self, classname, mode)
 144         return self._opendb('nodes.%s'%classname, mode)
 145
 146     def determine_db_type(self, path):
 147         ''' determine which DB wrote the class file
 148         '''
 149         db_type = ''
 150         if os.path.exists(path):
 151             db_type = whichdb.whichdb(path)
 152             if not db_type:
 153                 raise hyperdb.DatabaseError, "Couldn't identify database type"
 154         elif os.path.exists(path+'.db'):
 155             # if the path ends in '.db', it's a dbm database, whether
 156             # anydbm says it's dbhash or not!
 157             db_type = 'dbm'
 158         return db_type
 159
 160     def _opendb(self, name, mode):
 161         '''Low-level database opener that gets around anydbm/dbm
 162            eccentricities.
 163         '''
 164         if __debug__:
 165             print >>hyperdb.DEBUG, '_opendb', (self, name, mode)
 166
 167         # figure the class db type
 168         path = os.path.join(os.getcwd(), self.dir, name)
 169         db_type = self.determine_db_type(path)
 170
 171         # new database? let anydbm pick the best dbm
 172         if not db_type:
 173             if __debug__:
 174                 print >>hyperdb.DEBUG, "_opendb anydbm.open(%r, 'n')"%path
 175             return anydbm.open(path, 'n')
 176
 177         # open the database with the correct module
 178         try:
 179             dbm = __import__(db_type)
 180         except ImportError:
 181             raise hyperdb.DatabaseError, \
 182                 "Couldn't open database - the required module '%s'"\
 183                 " is not available"%db_type
 184         if __debug__:
 185             print >>hyperdb.DEBUG, "_opendb %r.open(%r, %r)"%(db_type, path,
 186                 mode)
 187         return dbm.open(path, mode)
 188
 189     def _lockdb(self, name):
 190         ''' Lock a database file
 191         '''
 192         path = os.path.join(os.getcwd(), self.dir, '%s.lock'%name)
 193         return acquire_lock(path)
 194
 195     #
 196     # Node IDs
 197     #
 198     def newid(self, classname):
 199         ''' Generate a new id for the given class
 200         '''
 201         # open the ids DB - create if if doesn't exist
 202         lock = self._lockdb('_ids')
 203         db = self._opendb('_ids', 'c')
 204         if db.has_key(classname):
 205             newid = db[classname] = str(int(db[classname]) + 1)
 206         else:
 207             # the count() bit is transitional - older dbs won't start at 1
 208             newid = str(self.getclass(classname).count()+1)
 209             db[classname] = newid
 210         db.close()
 211         release_lock(lock)
 212         return newid
 213
 214     #
 215     # Nodes
 216     #
 217     def addnode(self, classname, nodeid, node):
 218         ''' add the specified node to its class's db
 219         '''
 220         if __debug__:
 221             print >>hyperdb.DEBUG, 'addnode', (self, classname, nodeid, node)
 222         self.newnodes.setdefault(classname, {})[nodeid] = 1
 223         self.cache.setdefault(classname, {})[nodeid] = node
 224         self.savenode(classname, nodeid, node)
 225
 226     def setnode(self, classname, nodeid, node):
 227         ''' change the specified node
 228         '''
 229         if __debug__:
 230             print >>hyperdb.DEBUG, 'setnode', (self, classname, nodeid, node)
 231         self.dirtynodes.setdefault(classname, {})[nodeid] = 1
 232
 233         # can't set without having already loaded the node
 234         self.cache[classname][nodeid] = node
 235         self.savenode(classname, nodeid, node)
 236
 237     def savenode(self, classname, nodeid, node):
 238         ''' perform the saving of data specified by the set/addnode
 239         '''
 240         if __debug__:
 241             print >>hyperdb.DEBUG, 'savenode', (self, classname, nodeid, node)
 242         self.transactions.append((self._doSaveNode, (classname, nodeid, node)))
 243
 244     def getnode(self, classname, nodeid, db=None, cache=1):
 245         ''' get a node from the database
 246         '''
 247         if __debug__:
 248             print >>hyperdb.DEBUG, 'getnode', (self, classname, nodeid, db)
 249         if cache:
 250             # try the cache
 251             cache_dict = self.cache.setdefault(classname, {})
 252             if cache_dict.has_key(nodeid):
 253                 if __debug__:
 254                     print >>hyperdb.TRACE, 'get %s %s cached'%(classname,
 255                         nodeid)
 256                 return cache_dict[nodeid]
 257
 258         if __debug__:
 259             print >>hyperdb.TRACE, 'get %s %s'%(classname, nodeid)
 260
 261         # get from the database and save in the cache
 262         if db is None:
 263             db = self.getclassdb(classname)
 264         if not db.has_key(nodeid):
 265             raise IndexError, "no such %s %s"%(classname, nodeid)
 266
 267         # decode
 268         res = marshal.loads(db[nodeid])
 269
 270         # reverse the serialisation
 271         res = self.unserialise(classname, res)
 272
 273         # store off in the cache dict
 274         if cache:
 275             cache_dict[nodeid] = res
 276
 277         return res
 278
 279     def serialise(self, classname, node):
 280         '''Copy the node contents, converting non-marshallable data into
 281            marshallable data.
 282         '''
 283         if __debug__:
 284             print >>hyperdb.DEBUG, 'serialise', classname, node
 285         properties = self.getclass(classname).getprops()
 286         d = {}
 287         for k, v in node.items():
 288             # if the property doesn't exist, or is the "retired" flag then
 289             # it won't be in the properties dict
 290             if not properties.has_key(k):
 291                 d[k] = v
 292                 continue
 293
 294             # get the property spec
 295             prop = properties[k]
 296
 297             if isinstance(prop, Password):
 298                 d[k] = str(v)
 299             elif isinstance(prop, Date) and v is not None:
 300                 d[k] = v.get_tuple()
 301             elif isinstance(prop, Interval) and v is not None:
 302                 d[k] = v.get_tuple()
 303             else:
 304                 d[k] = v
 305         return d
 306
 307     def unserialise(self, classname, node):
 308         '''Decode the marshalled node data
 309         '''
 310         if __debug__:
 311             print >>hyperdb.DEBUG, 'unserialise', classname, node
 312         properties = self.getclass(classname).getprops()
 313         d = {}
 314         for k, v in node.items():
 315             # if the property doesn't exist, or is the "retired" flag then
 316             # it won't be in the properties dict
 317             if not properties.has_key(k):
 318                 d[k] = v
 319                 continue
 320
 321             # get the property spec
 322             prop = properties[k]
 323
 324             if isinstance(prop, Date) and v is not None:
 325                 d[k] = date.Date(v)
 326             elif isinstance(prop, Interval) and v is not None:
 327                 d[k] = date.Interval(v)
 328             elif isinstance(prop, Password):
 329                 p = password.Password()
 330                 p.unpack(v)
 331                 d[k] = p
 332             else:
 333                 d[k] = v
 334         return d
 335
 336     def hasnode(self, classname, nodeid, db=None):
 337         ''' determine if the database has a given node
 338         '''
 339         if __debug__:
 340             print >>hyperdb.DEBUG, 'hasnode', (self, classname, nodeid, db)
 341
 342         # try the cache
 343         cache = self.cache.setdefault(classname, {})
 344         if cache.has_key(nodeid):
 345             if __debug__:
 346                 print >>hyperdb.TRACE, 'has %s %s cached'%(classname, nodeid)
 347             return 1
 348         if __debug__:
 349             print >>hyperdb.TRACE, 'has %s %s'%(classname, nodeid)
 350
 351         # not in the cache - check the database
 352         if db is None:
 353             db = self.getclassdb(classname)
 354         res = db.has_key(nodeid)
 355         return res
 356
 357     def countnodes(self, classname, db=None):
 358         if __debug__:
 359             print >>hyperdb.DEBUG, 'countnodes', (self, classname, db)
 360         # include the new nodes not saved to the DB yet
 361         count = len(self.newnodes.get(classname, {}))
 362
 363         # and count those in the DB
 364         if db is None:
 365             db = self.getclassdb(classname)
 366         count = count + len(db.keys())
 367         return count
 368
 369     def getnodeids(self, classname, db=None):
 370         if __debug__:
 371             print >>hyperdb.DEBUG, 'getnodeids', (self, classname, db)
 372         # start off with the new nodes
 373         res = self.newnodes.get(classname, {}).keys()
 374
 375         if db is None:
 376             db = self.getclassdb(classname)
 377         res = res + db.keys()
 378         return res
 379
 380
 381     #
 382     # Files - special node properties
 383     # inherited from FileStorage
 384
 385     #
 386     # Journal
 387     #
 388     def addjournal(self, classname, nodeid, action, params):
 389         ''' Journal the Action
 390         'action' may be:
 391
 392             'create' or 'set' -- 'params' is a dictionary of property values
 393             'link' or 'unlink' -- 'params' is (classname, nodeid, propname)
 394             'retire' -- 'params' is None
 395         '''
 396         if __debug__:
 397             print >>hyperdb.DEBUG, 'addjournal', (self, classname, nodeid,
 398                 action, params)
 399         self.transactions.append((self._doSaveJournal, (classname, nodeid,
 400             action, params)))
 401
 402     def getjournal(self, classname, nodeid):
 403         ''' get the journal for id
 404         '''
 405         if __debug__:
 406             print >>hyperdb.DEBUG, 'getjournal', (self, classname, nodeid)
 407         # attempt to open the journal - in some rare cases, the journal may
 408         # not exist
 409         try:
 410             db = self._opendb('journals.%s'%classname, 'r')
 411         except anydbm.error, error:
 412             if str(error) == "need 'c' or 'n' flag to open new db": return []
 413             elif error.args[0] != 2: raise
 414             return []
 415         try:
 416             journal = marshal.loads(db[nodeid])
 417         except KeyError:
 418             db.close()
 419             raise KeyError, 'no such %s %s'%(classname, nodeid)
 420         db.close()
 421         res = []
 422         for entry in journal:
 423             (nodeid, date_stamp, user, action, params) = entry
 424             date_obj = date.Date(date_stamp)
 425             res.append((nodeid, date_obj, user, action, params))
 426         return res
 427
 428     def pack(self, pack_before):
 429         ''' delete all journal entries before 'pack_before' '''
 430         if __debug__:
 431             print >>hyperdb.DEBUG, 'packjournal', (self, pack_before)
 432
 433         pack_before = pack_before.get_tuple()
 434
 435         classes = self.getclasses()
 436
 437         # figure the class db type
 438
 439         for classname in classes:
 440             db_name = 'journals.%s'%classname
 441             path = os.path.join(os.getcwd(), self.dir, classname)
 442             db_type = self.determine_db_type(path)
 443             db = self._opendb(db_name, 'w')
 444
 445             for key in db.keys():
 446                 journal = marshal.loads(db[key])
 447                 l = []
 448                 last_set_entry = None
 449                 for entry in journal:
 450                     (nodeid, date_stamp, self.journaltag, action,
 451                         params) = entry
 452                     if date_stamp > pack_before or action == 'create':
 453                         l.append(entry)
 454                     elif action == 'set':
 455                         # grab the last set entry to keep information on
 456                         # activity
 457                         last_set_entry = entry
 458                 if last_set_entry:
 459                     date_stamp = last_set_entry[1]
 460                     # if the last set entry was made after the pack date
 461                     # then it is already in the list
 462                     if date_stamp < pack_before:
 463                         l.append(last_set_entry)
 464                 db[key] = marshal.dumps(l)
 465             if db_type == 'gdbm':
 466                 db.reorganize()
 467             db.close()
 468
 469
 470     #
 471     # Basic transaction support
 472     #
 473     def commit(self):
 474         ''' Commit the current transactions.
 475         '''
 476         if __debug__:
 477             print >>hyperdb.DEBUG, 'commit', (self,)
 478         # TODO: lock the DB
 479
 480         # keep a handle to all the database files opened
 481         self.databases = {}
 482
 483         # now, do all the transactions
 484         reindex = {}
 485         for method, args in self.transactions:
 486             reindex[method(*args)] = 1
 487
 488         # now close all the database files
 489         for db in self.databases.values():
 490             db.close()
 491         del self.databases
 492         # TODO: unlock the DB
 493
 494         # reindex the nodes that request it
 495         for classname, nodeid in filter(None, reindex.keys()):
 496             print >>hyperdb.DEBUG, 'commit.reindex', (classname, nodeid)
 497             self.getclass(classname).index(nodeid)
 498
 499         # save the indexer state
 500         self.indexer.save_index()
 501
 502         # all transactions committed, back to normal
 503         self.cache = {}
 504         self.dirtynodes = {}
 505         self.newnodes = {}
 506         self.transactions = []
 507
 508     def _doSaveNode(self, classname, nodeid, node):
 509         if __debug__:
 510             print >>hyperdb.DEBUG, '_doSaveNode', (self, classname, nodeid,
 511                 node)
 512
 513         # get the database handle
 514         db_name = 'nodes.%s'%classname
 515         if self.databases.has_key(db_name):
 516             db = self.databases[db_name]
 517         else:
 518             db = self.databases[db_name] = self.getclassdb(classname, 'c')
 519
 520         # now save the marshalled data
 521         db[nodeid] = marshal.dumps(self.serialise(classname, node))
 522
 523         # return the classname, nodeid so we reindex this content
 524         return (classname, nodeid)
 525
 526     def _doSaveJournal(self, classname, nodeid, action, params):
 527         # serialise first
 528         if action in ('set', 'create'):
 529             params = self.serialise(classname, params)
 530
 531         # create the journal entry
 532         entry = (nodeid, date.Date().get_tuple(), self.journaltag, action,
 533             params)
 534
 535         if __debug__:
 536             print >>hyperdb.DEBUG, '_doSaveJournal', entry
 537
 538         # get the database handle
 539         db_name = 'journals.%s'%classname
 540         if self.databases.has_key(db_name):
 541             db = self.databases[db_name]
 542         else:
 543             db = self.databases[db_name] = self._opendb(db_name, 'c')
 544
 545         # now insert the journal entry
 546         if db.has_key(nodeid):
 547             # append to existing
 548             s = db[nodeid]
 549             l = marshal.loads(s)
 550             l.append(entry)
 551         else:
 552             l = [entry]
 553
 554         db[nodeid] = marshal.dumps(l)
 555
 556     def rollback(self):
 557         ''' Reverse all actions from the current transaction.
 558         '''
 559         if __debug__:
 560             print >>hyperdb.DEBUG, 'rollback', (self, )
 561         for method, args in self.transactions:
 562             # delete temporary files
 563             if method == self._doStoreFile:
 564                 self._rollbackStoreFile(*args)
 565         self.cache = {}
 566         self.dirtynodes = {}
 567         self.newnodes = {}
 568         self.transactions = []
 569
 570 _marker = []
 571 class Class(hyperdb.Class):
 572     """The handle to a particular class of nodes in a hyperdatabase."""
 573
 574     def __init__(self, db, classname, **properties):
 575         """Create a new class with a given name and property specification.
 576
 577         'classname' must not collide with the name of an existing class,
 578         or a ValueError is raised.  The keyword arguments in 'properties'
 579         must map names to property objects, or a TypeError is raised.
 580         """
 581         if (properties.has_key('creation') or properties.has_key('activity')
 582                 or properties.has_key('creator')):
 583             raise ValueError, '"creation", "activity" and "creator" are '\
 584                 'reserved'
 585
 586         self.classname = classname
 587         self.properties = properties
 588         self.db = weakref.proxy(db)       # use a weak ref to avoid circularity
 589         self.key = ''
 590
 591         # should we journal changes (default yes)
 592         self.do_journal = 1
 593
 594         # do the db-related init stuff
 595         db.addclass(self)
 596
 597         self.auditors = {'create': [], 'set': [], 'retire': []}
 598         self.reactors = {'create': [], 'set': [], 'retire': []}
 599
 600     def enableJournalling(self):
 601         '''Turn journalling on for this class
 602         '''
 603         self.do_journal = 1
 604
 605     def disableJournalling(self):
 606         '''Turn journalling off for this class
 607         '''
 608         self.do_journal = 0
 609
 610     # Editing nodes:
 611
 612     def create(self, **propvalues):
 613         """Create a new node of this class and return its id.
 614
 615         The keyword arguments in 'propvalues' map property names to values.
 616
 617         The values of arguments must be acceptable for the types of their
 618         corresponding properties or a TypeError is raised.
 619
 620         If this class has a key property, it must be present and its value
 621         must not collide with other key strings or a ValueError is raised.
 622
 623         Any other properties on this class that are missing from the
 624         'propvalues' dictionary are set to None.
 625
 626         If an id in a link or multilink property does not refer to a valid
 627         node, an IndexError is raised.
 628
 629         These operations trigger detectors and can be vetoed.  Attempts
 630         to modify the "creation" or "activity" properties cause a KeyError.
 631         """
 632         if propvalues.has_key('id'):
 633             raise KeyError, '"id" is reserved'
 634
 635         if self.db.journaltag is None:
 636             raise DatabaseError, 'Database open read-only'
 637
 638         if propvalues.has_key('creation') or propvalues.has_key('activity'):
 639             raise KeyError, '"creation" and "activity" are reserved'
 640
 641         self.fireAuditors('create', None, propvalues)
 642
 643         # new node's id
 644         newid = self.db.newid(self.classname)
 645
 646         # validate propvalues
 647         num_re = re.compile('^\d+$')
 648         for key, value in propvalues.items():
 649             if key == self.key:
 650                 try:
 651                     self.lookup(value)
 652                 except KeyError:
 653                     pass
 654                 else:
 655                     raise ValueError, 'node with key "%s" exists'%value
 656
 657             # try to handle this property
 658             try:
 659                 prop = self.properties[key]
 660             except KeyError:
 661                 raise KeyError, '"%s" has no property "%s"'%(self.classname,
 662                     key)
 663
 664             if isinstance(prop, Link):
 665                 if type(value) != type(''):
 666                     raise ValueError, 'link value must be String'
 667                 link_class = self.properties[key].classname
 668                 # if it isn't a number, it's a key
 669                 if not num_re.match(value):
 670                     try:
 671                         value = self.db.classes[link_class].lookup(value)
 672                     except (TypeError, KeyError):
 673                         raise IndexError, 'new property "%s": %s not a %s'%(
 674                             key, value, link_class)
 675                 elif not self.db.hasnode(link_class, value):
 676                     raise IndexError, '%s has no node %s'%(link_class, value)
 677
 678                 # save off the value
 679                 propvalues[key] = value
 680
 681                 # register the link with the newly linked node
 682                 if self.do_journal and self.properties[key].do_journal:
 683                     self.db.addjournal(link_class, value, 'link',
 684                         (self.classname, newid, key))
 685
 686             elif isinstance(prop, Multilink):
 687                 if type(value) != type([]):
 688                     raise TypeError, 'new property "%s" not a list of ids'%key
 689
 690                 # clean up and validate the list of links
 691                 link_class = self.properties[key].classname
 692                 l = []
 693                 for entry in value:
 694                     if type(entry) != type(''):
 695                         raise ValueError, '"%s" link value (%s) must be '\
 696                             'String'%(key, value)
 697                     # if it isn't a number, it's a key
 698                     if not num_re.match(entry):
 699                         try:
 700                             entry = self.db.classes[link_class].lookup(entry)
 701                         except (TypeError, KeyError):
 702                             raise IndexError, 'new property "%s": %s not a %s'%(
 703                                 key, entry, self.properties[key].classname)
 704                     l.append(entry)
 705                 value = l
 706                 propvalues[key] = value
 707
 708                 # handle additions
 709                 for id in value:
 710                     if not self.db.hasnode(link_class, id):
 711                         raise IndexError, '%s has no node %s'%(link_class, id)
 712                     # register the link with the newly linked node
 713                     if self.do_journal and self.properties[key].do_journal:
 714                         self.db.addjournal(link_class, id, 'link',
 715                             (self.classname, newid, key))
 716
 717             elif isinstance(prop, String):
 718                 if type(value) != type(''):
 719                     raise TypeError, 'new property "%s" not a string'%key
 720
 721             elif isinstance(prop, Password):
 722                 if not isinstance(value, password.Password):
 723                     raise TypeError, 'new property "%s" not a Password'%key
 724
 725             elif isinstance(prop, Date):
 726                 if value is not None and not isinstance(value, date.Date):
 727                     raise TypeError, 'new property "%s" not a Date'%key
 728
 729             elif isinstance(prop, Interval):
 730                 if value is not None and not isinstance(value, date.Interval):
 731                     raise TypeError, 'new property "%s" not an Interval'%key
 732
 733             elif isinstance(prop, Number):
 734                 try:
 735                     int(value)
 736                 except TypeError:
 737                     raise TypeError, 'new property "%s" not numeric' % propname
 738
 739             elif isinstance(prop, Boolean):
 740                 try:
 741                     int(value)
 742                 except TypeError:
 743                     raise TypeError, 'new property "%s" is not boolean' % propname
 744
 745         # make sure there's data where there needs to be
 746         for key, prop in self.properties.items():
 747             if propvalues.has_key(key):
 748                 continue
 749             if key == self.key:
 750                 raise ValueError, 'key property "%s" is required'%key
 751             if isinstance(prop, Multilink):
 752                 propvalues[key] = []
 753             else:
 754                 propvalues[key] = None
 755
 756         # done
 757         self.db.addnode(self.classname, newid, propvalues)
 758         if self.do_journal:
 759             self.db.addjournal(self.classname, newid, 'create', propvalues)
 760
 761         self.fireReactors('create', newid, None)
 762
 763         return newid
 764
 765     def get(self, nodeid, propname, default=_marker, cache=1):
 766         """Get the value of a property on an existing node of this class.
 767
 768         'nodeid' must be the id of an existing node of this class or an
 769         IndexError is raised.  'propname' must be the name of a property
 770         of this class or a KeyError is raised.
 771
 772         'cache' indicates whether the transaction cache should be queried
 773         for the node. If the node has been modified and you need to
 774         determine what its values prior to modification are, you need to
 775         set cache=0.
 776
 777         Attempts to get the "creation" or "activity" properties should
 778         do the right thing.
 779         """
 780         if propname == 'id':
 781             return nodeid
 782
 783         if propname == 'creation':
 784             if not self.do_journal:
 785                 raise ValueError, 'Journalling is disabled for this class'
 786             journal = self.db.getjournal(self.classname, nodeid)
 787             if journal:
 788                 return self.db.getjournal(self.classname, nodeid)[0][1]
 789             else:
 790                 # on the strange chance that there's no journal
 791                 return date.Date()
 792         if propname == 'activity':
 793             if not self.do_journal:
 794                 raise ValueError, 'Journalling is disabled for this class'
 795             journal = self.db.getjournal(self.classname, nodeid)
 796             if journal:
 797                 return self.db.getjournal(self.classname, nodeid)[-1][1]
 798             else:
 799                 # on the strange chance that there's no journal
 800                 return date.Date()
 801         if propname == 'creator':
 802             if not self.do_journal:
 803                 raise ValueError, 'Journalling is disabled for this class'
 804             journal = self.db.getjournal(self.classname, nodeid)
 805             if journal:
 806                 name = self.db.getjournal(self.classname, nodeid)[0][2]
 807             else:
 808                 return None
 809             return self.db.user.lookup(name)
 810
 811         # get the property (raises KeyErorr if invalid)
 812         prop = self.properties[propname]
 813
 814         # get the node's dict
 815         d = self.db.getnode(self.classname, nodeid, cache=cache)
 816
 817         if not d.has_key(propname):
 818             if default is _marker:
 819                 if isinstance(prop, Multilink):
 820                     return []
 821                 else:
 822                     return None
 823             else:
 824                 return default
 825
 826         return d[propname]
 827
 828     # XXX not in spec
 829     def getnode(self, nodeid, cache=1):
 830         ''' Return a convenience wrapper for the node.
 831
 832         'nodeid' must be the id of an existing node of this class or an
 833         IndexError is raised.
 834
 835         'cache' indicates whether the transaction cache should be queried
 836         for the node. If the node has been modified and you need to
 837         determine what its values prior to modification are, you need to
 838         set cache=0.
 839         '''
 840         return Node(self, nodeid, cache=cache)
 841
 842     def set(self, nodeid, **propvalues):
 843         """Modify a property on an existing node of this class.
 844
 845         'nodeid' must be the id of an existing node of this class or an
 846         IndexError is raised.
 847
 848         Each key in 'propvalues' must be the name of a property of this
 849         class or a KeyError is raised.
 850
 851         All values in 'propvalues' must be acceptable types for their
 852         corresponding properties or a TypeError is raised.
 853
 854         If the value of the key property is set, it must not collide with
 855         other key strings or a ValueError is raised.
 856
 857         If the value of a Link or Multilink property contains an invalid
 858         node id, a ValueError is raised.
 859
 860         These operations trigger detectors and can be vetoed.  Attempts
 861         to modify the "creation" or "activity" properties cause a KeyError.
 862         """
 863         if not propvalues:
 864             return
 865
 866         if propvalues.has_key('creation') or propvalues.has_key('activity'):
 867             raise KeyError, '"creation" and "activity" are reserved'
 868
 869         if propvalues.has_key('id'):
 870             raise KeyError, '"id" is reserved'
 871
 872         if self.db.journaltag is None:
 873             raise DatabaseError, 'Database open read-only'
 874
 875         self.fireAuditors('set', nodeid, propvalues)
 876         # Take a copy of the node dict so that the subsequent set
 877         # operation doesn't modify the oldvalues structure.
 878         try:
 879             # try not using the cache initially
 880             oldvalues = copy.deepcopy(self.db.getnode(self.classname, nodeid,
 881                 cache=0))
 882         except IndexError:
 883             # this will be needed if somone does a create() and set()
 884             # with no intervening commit()
 885             oldvalues = copy.deepcopy(self.db.getnode(self.classname, nodeid))
 886
 887         node = self.db.getnode(self.classname, nodeid)
 888         if node.has_key(self.db.RETIRED_FLAG):
 889             raise IndexError
 890         num_re = re.compile('^\d+$')
 891
 892         # if the journal value is to be different, store it in here
 893         journalvalues = {}
 894
 895         for propname, value in propvalues.items():
 896             # check to make sure we're not duplicating an existing key
 897             if propname == self.key and node[propname] != value:
 898                 try:
 899                     self.lookup(value)
 900                 except KeyError:
 901                     pass
 902                 else:
 903                     raise ValueError, 'node with key "%s" exists'%value
 904
 905             # this will raise the KeyError if the property isn't valid
 906             # ... we don't use getprops() here because we only care about
 907             # the writeable properties.
 908             prop = self.properties[propname]
 909
 910             # if the value's the same as the existing value, no sense in
 911             # doing anything
 912             if node.has_key(propname) and value == node[propname]:
 913                 del propvalues[propname]
 914                 continue
 915
 916             # do stuff based on the prop type
 917             if isinstance(prop, Link):
 918                 link_class = self.properties[propname].classname
 919                 # if it isn't a number, it's a key
 920                 if type(value) != type(''):
 921                     raise ValueError, 'link value must be String'
 922                 if not num_re.match(value):
 923                     try:
 924                         value = self.db.classes[link_class].lookup(value)
 925                     except (TypeError, KeyError):
 926                         raise IndexError, 'new property "%s": %s not a %s'%(
 927                             propname, value, self.properties[propname].classname)
 928
 929                 if not self.db.hasnode(link_class, value):
 930                     raise IndexError, '%s has no node %s'%(link_class, value)
 931
 932                 if self.do_journal and self.properties[propname].do_journal:
 933                     # register the unlink with the old linked node
 934                     if node[propname] is not None:
 935                         self.db.addjournal(link_class, node[propname], 'unlink',
 936                             (self.classname, nodeid, propname))
 937
 938                     # register the link with the newly linked node
 939                     if value is not None:
 940                         self.db.addjournal(link_class, value, 'link',
 941                             (self.classname, nodeid, propname))
 942
 943             elif isinstance(prop, Multilink):
 944                 if type(value) != type([]):
 945                     raise TypeError, 'new property "%s" not a list of'\
 946                         ' ids'%propname
 947                 link_class = self.properties[propname].classname
 948                 l = []
 949                 for entry in value:
 950                     # if it isn't a number, it's a key
 951                     if type(entry) != type(''):
 952                         raise ValueError, 'new property "%s" link value ' \
 953                             'must be a string'%propname
 954                     if not num_re.match(entry):
 955                         try:
 956                             entry = self.db.classes[link_class].lookup(entry)
 957                         except (TypeError, KeyError):
 958                             raise IndexError, 'new property "%s": %s not a %s'%(
 959                                 propname, entry,
 960                                 self.properties[propname].classname)
 961                     l.append(entry)
 962                 value = l
 963                 propvalues[propname] = value
 964
 965                 # figure the journal entry for this property
 966                 add = []
 967                 remove = []
 968
 969                 # handle removals
 970                 if node.has_key(propname):
 971                     l = node[propname]
 972                 else:
 973                     l = []
 974                 for id in l[:]:
 975                     if id in value:
 976                         continue
 977                     # register the unlink with the old linked node
 978                     if self.do_journal and self.properties[propname].do_journal:
 979                         self.db.addjournal(link_class, id, 'unlink',
 980                             (self.classname, nodeid, propname))
 981                     l.remove(id)
 982                     remove.append(id)
 983
 984                 # handle additions
 985                 for id in value:
 986                     if not self.db.hasnode(link_class, id):
 987                         raise IndexError, '%s has no node %s'%(link_class, id)
 988                     if id in l:
 989                         continue
 990                     # register the link with the newly linked node
 991                     if self.do_journal and self.properties[propname].do_journal:
 992                         self.db.addjournal(link_class, id, 'link',
 993                             (self.classname, nodeid, propname))
 994                     l.append(id)
 995                     add.append(id)
 996
 997                 # figure the journal entry
 998                 l = []
 999                 if add:
1000                     l.append(('add', add))
1001                 if remove:
1002                     l.append(('remove', remove))
1003                 if l:
1004                     journalvalues[propname] = tuple(l)
1005
1006             elif isinstance(prop, String):
1007                 if value is not None and type(value) != type(''):
1008                     raise TypeError, 'new property "%s" not a string'%propname
1009
1010             elif isinstance(prop, Password):
1011                 if not isinstance(value, password.Password):
1012                     raise TypeError, 'new property "%s" not a Password'%propname
1013                 propvalues[propname] = value
1014
1015             elif value is not None and isinstance(prop, Date):
1016                 if not isinstance(value, date.Date):
1017                     raise TypeError, 'new property "%s" not a Date'% propname
1018                 propvalues[propname] = value
1019
1020             elif value is not None and isinstance(prop, Interval):
1021                 if not isinstance(value, date.Interval):
1022                     raise TypeError, 'new property "%s" not an '\
1023                         'Interval'%propname
1024                 propvalues[propname] = value
1025
1026             elif value is not None and isinstance(prop, Number):
1027                 # TODO: should we store floats too?
1028                 try:
1029                     int(value)
1030                 except TypeError:
1031                     raise TypeError, 'new property "%s" not numeric' % propname
1032
1033             elif value is not None and isinstance(prop, Boolean):
1034                 if isinstance(value, type('')):
1035                     s = value.lower()
1036                     if s in ('0', 'false', 'no'):
1037                         value = 0
1038                     elif s in ('1', 'true', 'yes'):
1039                         value = 1
1040                     else:
1041                         raise TypeError, 'new property "%s" not '\
1042                             'boolean'%propname
1043                 else:
1044                     try:
1045                         int(value)
1046                     except TypeError:
1047                         raise TypeError, 'new property "%s" not '\
1048                             'boolean'%propname
1049
1050             node[propname] = value
1051
1052         # nothing to do?
1053         if not propvalues:
1054             return
1055
1056         # do the set, and journal it
1057         self.db.setnode(self.classname, nodeid, node)
1058
1059         if self.do_journal:
1060             propvalues.update(journalvalues)
1061             self.db.addjournal(self.classname, nodeid, 'set', propvalues)
1062
1063         self.fireReactors('set', nodeid, oldvalues)
1064
1065     def retire(self, nodeid):
1066         """Retire a node.
1067
1068         The properties on the node remain available from the get() method,
1069         and the node's id is never reused.
1070
1071         Retired nodes are not returned by the find(), list(), or lookup()
1072         methods, and other nodes may reuse the values of their key properties.
1073
1074         These operations trigger detectors and can be vetoed.  Attempts
1075         to modify the "creation" or "activity" properties cause a KeyError.
1076         """
1077         if self.db.journaltag is None:
1078             raise DatabaseError, 'Database open read-only'
1079
1080         self.fireAuditors('retire', nodeid, None)
1081
1082         node = self.db.getnode(self.classname, nodeid)
1083         node[self.db.RETIRED_FLAG] = 1
1084         self.db.setnode(self.classname, nodeid, node)
1085         if self.do_journal:
1086             self.db.addjournal(self.classname, nodeid, 'retired', None)
1087
1088         self.fireReactors('retire', nodeid, None)
1089
1090     def history(self, nodeid):
1091         """Retrieve the journal of edits on a particular node.
1092
1093         'nodeid' must be the id of an existing node of this class or an
1094         IndexError is raised.
1095
1096         The returned list contains tuples of the form
1097
1098             (date, tag, action, params)
1099
1100         'date' is a Timestamp object specifying the time of the change and
1101         'tag' is the journaltag specified when the database was opened.
1102         """
1103         if not self.do_journal:
1104             raise ValueError, 'Journalling is disabled for this class'
1105         return self.db.getjournal(self.classname, nodeid)
1106
1107     # Locating nodes:
1108     def hasnode(self, nodeid):
1109         '''Determine if the given nodeid actually exists
1110         '''
1111         return self.db.hasnode(self.classname, nodeid)
1112
1113     def setkey(self, propname):
1114         """Select a String property of this class to be the key property.
1115
1116         'propname' must be the name of a String property of this class or
1117         None, or a TypeError is raised.  The values of the key property on
1118         all existing nodes must be unique or a ValueError is raised. If the
1119         property doesn't exist, KeyError is raised.
1120         """
1121         prop = self.getprops()[propname]
1122         if not isinstance(prop, String):
1123             raise TypeError, 'key properties must be String'
1124         self.key = propname
1125
1126     def getkey(self):
1127         """Return the name of the key property for this class or None."""
1128         return self.key
1129
1130     def labelprop(self, default_to_id=0):
1131         ''' Return the property name for a label for the given node.
1132
1133         This method attempts to generate a consistent label for the node.
1134         It tries the following in order:
1135             1. key property
1136             2. "name" property
1137             3. "title" property
1138             4. first property from the sorted property name list
1139         '''
1140         k = self.getkey()
1141         if  k:
1142             return k
1143         props = self.getprops()
1144         if props.has_key('name'):
1145             return 'name'
1146         elif props.has_key('title'):
1147             return 'title'
1148         if default_to_id:
1149             return 'id'
1150         props = props.keys()
1151         props.sort()
1152         return props[0]
1153
1154     # TODO: set up a separate index db file for this? profile?
1155     def lookup(self, keyvalue):
1156         """Locate a particular node by its key property and return its id.
1157
1158         If this class has no key property, a TypeError is raised.  If the
1159         'keyvalue' matches one of the values for the key property among
1160         the nodes in this class, the matching node's id is returned;
1161         otherwise a KeyError is raised.
1162         """
1163         cldb = self.db.getclassdb(self.classname)
1164         try:
1165             for nodeid in self.db.getnodeids(self.classname, cldb):
1166                 node = self.db.getnode(self.classname, nodeid, cldb)
1167                 if node.has_key(self.db.RETIRED_FLAG):
1168                     continue
1169                 if node[self.key] == keyvalue:
1170                     cldb.close()
1171                     return nodeid
1172         finally:
1173             cldb.close()
1174         raise KeyError, keyvalue
1175
1176     # XXX: change from spec - allows multiple props to match
1177     def find(self, **propspec):
1178         """Get the ids of nodes in this class which link to the given nodes.
1179
1180         'propspec' consists of keyword args propname={nodeid:1,}
1181           'propname' must be the name of a property in this class, or a
1182             KeyError is raised.  That property must be a Link or Multilink
1183             property, or a TypeError is raised.
1184
1185         Any node in this class whose 'propname' property links to any of the
1186         nodeids will be returned. Used by the full text indexing, which knows
1187         that "foo" occurs in msg1, msg3 and file7, so we have hits on these issues:
1188             db.issue.find(messages={'1':1,'3':1}, files={'7':1})
1189         """
1190         propspec = propspec.items()
1191         for propname, nodeids in propspec:
1192             # check the prop is OK
1193             prop = self.properties[propname]
1194             if not isinstance(prop, Link) and not isinstance(prop, Multilink):
1195                 raise TypeError, "'%s' not a Link/Multilink property"%propname
1196             #XXX edit is expensive and of questionable use
1197             #for nodeid in nodeids:
1198             #    if not self.db.hasnode(prop.classname, nodeid):
1199             #        raise ValueError, '%s has no node %s'%(prop.classname, nodeid)
1200
1201         # ok, now do the find
1202         cldb = self.db.getclassdb(self.classname)
1203         l = []
1204         try:
1205             for id in self.db.getnodeids(self.classname, db=cldb):
1206                 node = self.db.getnode(self.classname, id, db=cldb)
1207                 if node.has_key(self.db.RETIRED_FLAG):
1208                     continue
1209                 for propname, nodeids in propspec:
1210                     # can't test if the node doesn't have this property
1211                     if not node.has_key(propname):
1212                         continue
1213                     if type(nodeids) is type(''):
1214                         nodeids = {nodeids:1}
1215                     prop = self.properties[propname]
1216                     value = node[propname]
1217                     if isinstance(prop, Link) and nodeids.has_key(value):
1218                         l.append(id)
1219                         break
1220                     elif isinstance(prop, Multilink):
1221                         hit = 0
1222                         for v in value:
1223                             if nodeids.has_key(v):
1224                                 l.append(id)
1225                                 hit = 1
1226                                 break
1227                         if hit:
1228                             break
1229         finally:
1230             cldb.close()
1231         return l
1232
1233     def stringFind(self, **requirements):
1234         """Locate a particular node by matching a set of its String
1235         properties in a caseless search.
1236
1237         If the property is not a String property, a TypeError is raised.
1238
1239         The return is a list of the id of all nodes that match.
1240         """
1241         for propname in requirements.keys():
1242             prop = self.properties[propname]
1243             if isinstance(not prop, String):
1244                 raise TypeError, "'%s' not a String property"%propname
1245             requirements[propname] = requirements[propname].lower()
1246         l = []
1247         cldb = self.db.getclassdb(self.classname)
1248         try:
1249             for nodeid in self.db.getnodeids(self.classname, cldb):
1250                 node = self.db.getnode(self.classname, nodeid, cldb)
1251                 if node.has_key(self.db.RETIRED_FLAG):
1252                     continue
1253                 for key, value in requirements.items():
1254                     if node[key] and node[key].lower() != value:
1255                         break
1256                 else:
1257                     l.append(nodeid)
1258         finally:
1259             cldb.close()
1260         return l
1261
1262     def list(self):
1263         """Return a list of the ids of the active nodes in this class."""
1264         l = []
1265         cn = self.classname
1266         cldb = self.db.getclassdb(cn)
1267         try:
1268             for nodeid in self.db.getnodeids(cn, cldb):
1269                 node = self.db.getnode(cn, nodeid, cldb)
1270                 if node.has_key(self.db.RETIRED_FLAG):
1271                     continue
1272                 l.append(nodeid)
1273         finally:
1274             cldb.close()
1275         l.sort()
1276         return l
1277
1278     # XXX not in spec
1279     def filter(self, search_matches, filterspec, sort, group,
1280             num_re = re.compile('^\d+$')):
1281         ''' Return a list of the ids of the active nodes in this class that
1282             match the 'filter' spec, sorted by the group spec and then the
1283             sort spec
1284         '''
1285         cn = self.classname
1286
1287         # optimise filterspec
1288         l = []
1289         props = self.getprops()
1290         for k, v in filterspec.items():
1291             propclass = props[k]
1292             if isinstance(propclass, Link):
1293                 if type(v) is not type([]):
1294                     v = [v]
1295                 # replace key values with node ids
1296                 u = []
1297                 link_class =  self.db.classes[propclass.classname]
1298                 for entry in v:
1299                     if entry == '-1': entry = None
1300                     elif not num_re.match(entry):
1301                         try:
1302                             entry = link_class.lookup(entry)
1303                         except (TypeError,KeyError):
1304                             raise ValueError, 'property "%s": %s not a %s'%(
1305                                 k, entry, self.properties[k].classname)
1306                     u.append(entry)
1307
1308                 l.append((0, k, u))
1309             elif isinstance(propclass, Multilink):
1310                 if type(v) is not type([]):
1311                     v = [v]
1312                 # replace key values with node ids
1313                 u = []
1314                 link_class =  self.db.classes[propclass.classname]
1315                 for entry in v:
1316                     if not num_re.match(entry):
1317                         try:
1318                             entry = link_class.lookup(entry)
1319                         except (TypeError,KeyError):
1320                             raise ValueError, 'new property "%s": %s not a %s'%(
1321                                 k, entry, self.properties[k].classname)
1322                     u.append(entry)
1323                 l.append((1, k, u))
1324             elif isinstance(propclass, String):
1325                 # simple glob searching
1326                 v = re.sub(r'([\|\{\}\\\.\+\[\]\(\)])', r'\\\1', v)
1327                 v = v.replace('?', '.')
1328                 v = v.replace('*', '.*?')
1329                 l.append((2, k, re.compile(v, re.I)))
1330             elif isinstance(propclass, Boolean):
1331                 if type(v) is type(''):
1332                     bv = v.lower() in ('yes', 'true', 'on', '1')
1333                 else:
1334                     bv = v
1335                 l.append((6, k, bv))
1336             elif isinstance(propclass, Number):
1337                 l.append((6, k, int(v)))
1338             else:
1339                 l.append((6, k, v))
1340         filterspec = l
1341
1342         # now, find all the nodes that are active and pass filtering
1343         l = []
1344         cldb = self.db.getclassdb(cn)
1345         try:
1346             for nodeid in self.db.getnodeids(cn, cldb):
1347                 node = self.db.getnode(cn, nodeid, cldb)
1348                 if node.has_key(self.db.RETIRED_FLAG):
1349                     continue
1350                 # apply filter
1351                 for t, k, v in filterspec:
1352                     # this node doesn't have this property, so reject it
1353                     if not node.has_key(k): break
1354
1355                     if t == 0 and node[k] not in v:
1356                         # link - if this node'd property doesn't appear in the
1357                         # filterspec's nodeid list, skip it
1358                         break
1359                     elif t == 1:
1360                         # multilink - if any of the nodeids required by the
1361                         # filterspec aren't in this node's property, then skip
1362                         # it
1363                         for value in v:
1364                             if value not in node[k]:
1365                                 break
1366                         else:
1367                             continue
1368                         break
1369                     elif t == 2 and (node[k] is None or not v.search(node[k])):
1370                         # RE search
1371                         break
1372                     elif t == 6 and node[k] != v:
1373                         # straight value comparison for the other types
1374                         break
1375                 else:
1376                     l.append((nodeid, node))
1377         finally:
1378             cldb.close()
1379         l.sort()
1380
1381         # filter based on full text search
1382         if search_matches is not None:
1383             k = []
1384             l_debug = []
1385             for v in l:
1386                 l_debug.append(v[0])
1387                 if search_matches.has_key(v[0]):
1388                     k.append(v)
1389             l = k
1390
1391         # optimise sort
1392         m = []
1393         for entry in sort:
1394             if entry[0] != '-':
1395                 m.append(('+', entry))
1396             else:
1397                 m.append((entry[0], entry[1:]))
1398         sort = m
1399
1400         # optimise group
1401         m = []
1402         for entry in group:
1403             if entry[0] != '-':
1404                 m.append(('+', entry))
1405             else:
1406                 m.append((entry[0], entry[1:]))
1407         group = m
1408         # now, sort the result
1409         def sortfun(a, b, sort=sort, group=group, properties=self.getprops(),
1410                 db = self.db, cl=self):
1411             a_id, an = a
1412             b_id, bn = b
1413             # sort by group and then sort
1414             for list in group, sort:
1415                 for dir, prop in list:
1416                     # sorting is class-specific
1417                     propclass = properties[prop]
1418
1419                     # handle the properties that might be "faked"
1420                     # also, handle possible missing properties
1421                     try:
1422                         if not an.has_key(prop):
1423                             an[prop] = cl.get(a_id, prop)
1424                         av = an[prop]
1425                     except KeyError:
1426                         # the node doesn't have a value for this property
1427                         if isinstance(propclass, Multilink): av = []
1428                         else: av = ''
1429                     try:
1430                         if not bn.has_key(prop):
1431                             bn[prop] = cl.get(b_id, prop)
1432                         bv = bn[prop]
1433                     except KeyError:
1434                         # the node doesn't have a value for this property
1435                         if isinstance(propclass, Multilink): bv = []
1436                         else: bv = ''
1437
1438                     # String and Date values are sorted in the natural way
1439                     if isinstance(propclass, String):
1440                         # clean up the strings
1441                         if av and av[0] in string.uppercase:
1442                             av = an[prop] = av.lower()
1443                         if bv and bv[0] in string.uppercase:
1444                             bv = bn[prop] = bv.lower()
1445                     if (isinstance(propclass, String) or
1446                             isinstance(propclass, Date)):
1447                         # it might be a string that's really an integer
1448                         try:
1449                             av = int(av)
1450                             bv = int(bv)
1451                         except:
1452                             pass
1453                         if dir == '+':
1454                             r = cmp(av, bv)
1455                             if r != 0: return r
1456                         elif dir == '-':
1457                             r = cmp(bv, av)
1458                             if r != 0: return r
1459
1460                     # Link properties are sorted according to the value of
1461                     # the "order" property on the linked nodes if it is
1462                     # present; or otherwise on the key string of the linked
1463                     # nodes; or finally on  the node ids.
1464                     elif isinstance(propclass, Link):
1465                         link = db.classes[propclass.classname]
1466                         if av is None and bv is not None: return -1
1467                         if av is not None and bv is None: return 1
1468                         if av is None and bv is None: continue
1469                         if link.getprops().has_key('order'):
1470                             if dir == '+':
1471                                 r = cmp(link.get(av, 'order'),
1472                                     link.get(bv, 'order'))
1473                                 if r != 0: return r
1474                             elif dir == '-':
1475                                 r = cmp(link.get(bv, 'order'),
1476                                     link.get(av, 'order'))
1477                                 if r != 0: return r
1478                         elif link.getkey():
1479                             key = link.getkey()
1480                             if dir == '+':
1481                                 r = cmp(link.get(av, key), link.get(bv, key))
1482                                 if r != 0: return r
1483                             elif dir == '-':
1484                                 r = cmp(link.get(bv, key), link.get(av, key))
1485                                 if r != 0: return r
1486                         else:
1487                             if dir == '+':
1488                                 r = cmp(av, bv)
1489                                 if r != 0: return r
1490                             elif dir == '-':
1491                                 r = cmp(bv, av)
1492                                 if r != 0: return r
1493
1494                     # Multilink properties are sorted according to how many
1495                     # links are present.
1496                     elif isinstance(propclass, Multilink):
1497                         if dir == '+':
1498                             r = cmp(len(av), len(bv))
1499                             if r != 0: return r
1500                         elif dir == '-':
1501                             r = cmp(len(bv), len(av))
1502                             if r != 0: return r
1503                     elif isinstance(propclass, Number) or isinstance(propclass, Boolean):
1504                         if dir == '+':
1505                             r = cmp(av, bv)
1506                         elif dir == '-':
1507                             r = cmp(bv, av)
1508
1509                 # end for dir, prop in list:
1510             # end for list in sort, group:
1511             # if all else fails, compare the ids
1512             return cmp(a[0], b[0])
1513
1514         l.sort(sortfun)
1515         return [i[0] for i in l]
1516
1517     def count(self):
1518         """Get the number of nodes in this class.
1519
1520         If the returned integer is 'numnodes', the ids of all the nodes
1521         in this class run from 1 to numnodes, and numnodes+1 will be the
1522         id of the next node to be created in this class.
1523         """
1524         return self.db.countnodes(self.classname)
1525
1526     # Manipulating properties:
1527
1528     def getprops(self, protected=1):
1529         """Return a dictionary mapping property names to property objects.
1530            If the "protected" flag is true, we include protected properties -
1531            those which may not be modified.
1532
1533            In addition to the actual properties on the node, these
1534            methods provide the "creation" and "activity" properties. If the
1535            "protected" flag is true, we include protected properties - those
1536            which may not be modified.
1537         """
1538         d = self.properties.copy()
1539         if protected:
1540             d['id'] = String()
1541             d['creation'] = hyperdb.Date()
1542             d['activity'] = hyperdb.Date()
1543             d['creator'] = hyperdb.Link("user")
1544         return d
1545
1546     def addprop(self, **properties):
1547         """Add properties to this class.
1548
1549         The keyword arguments in 'properties' must map names to property
1550         objects, or a TypeError is raised.  None of the keys in 'properties'
1551         may collide with the names of existing properties, or a ValueError
1552         is raised before any properties have been added.
1553         """
1554         for key in properties.keys():
1555             if self.properties.has_key(key):
1556                 raise ValueError, key
1557         self.properties.update(properties)
1558
1559     def index(self, nodeid):
1560         '''Add (or refresh) the node to search indexes
1561         '''
1562         # find all the String properties that have indexme
1563         for prop, propclass in self.getprops().items():
1564             if isinstance(propclass, String) and propclass.indexme:
1565                 # and index them under (classname, nodeid, property)
1566                 self.db.indexer.add_text((self.classname, nodeid, prop),
1567                     str(self.get(nodeid, prop)))
1568
1569     #
1570     # Detector interface
1571     #
1572     def audit(self, event, detector):
1573         """Register a detector
1574         """
1575         l = self.auditors[event]
1576         if detector not in l:
1577             self.auditors[event].append(detector)
1578
1579     def fireAuditors(self, action, nodeid, newvalues):
1580         """Fire all registered auditors.
1581         """
1582         for audit in self.auditors[action]:
1583             audit(self.db, self, nodeid, newvalues)
1584
1585     def react(self, event, detector):
1586         """Register a detector
1587         """
1588         l = self.reactors[event]
1589         if detector not in l:
1590             self.reactors[event].append(detector)
1591
1592     def fireReactors(self, action, nodeid, oldvalues):
1593         """Fire all registered reactors.
1594         """
1595         for react in self.reactors[action]:
1596             react(self.db, self, nodeid, oldvalues)
1597
1598 class FileClass(Class):
1599     '''This class defines a large chunk of data. To support this, it has a
1600        mandatory String property "content" which is typically saved off
1601        externally to the hyperdb.
1602
1603        The default MIME type of this data is defined by the
1604        "default_mime_type" class attribute, which may be overridden by each
1605        node if the class defines a "type" String property.
1606     '''
1607     default_mime_type = 'text/plain'
1608
1609     def create(self, **propvalues):
1610         ''' snaffle the file propvalue and store in a file
1611         '''
1612         content = propvalues['content']
1613         del propvalues['content']
1614         newid = Class.create(self, **propvalues)
1615         self.db.storefile(self.classname, newid, None, content)
1616         return newid
1617
1618     def get(self, nodeid, propname, default=_marker, cache=1):
1619         ''' trap the content propname and get it from the file
1620         '''
1621
1622         poss_msg = 'Possibly a access right configuration problem.'
1623         if propname == 'content':
1624             try:
1625                 return self.db.getfile(self.classname, nodeid, None)
1626             except IOError, (strerror):
1627                 # BUG: by catching this we donot see an error in the log.
1628                 return 'ERROR reading file: %s%s\n%s\n%s'%(
1629                         self.classname, nodeid, poss_msg, strerror)
1630         if default is not _marker:
1631             return Class.get(self, nodeid, propname, default, cache=cache)
1632         else:
1633             return Class.get(self, nodeid, propname, cache=cache)
1634
1635     def getprops(self, protected=1):
1636         ''' In addition to the actual properties on the node, these methods
1637             provide the "content" property. If the "protected" flag is true,
1638             we include protected properties - those which may not be
1639             modified.
1640         '''
1641         d = Class.getprops(self, protected=protected).copy()
1642         if protected:
1643             d['content'] = hyperdb.String()
1644         return d
1645
1646     def index(self, nodeid):
1647         ''' Index the node in the search index.
1648
1649             We want to index the content in addition to the normal String
1650             property indexing.
1651         '''
1652         # perform normal indexing
1653         Class.index(self, nodeid)
1654
1655         # get the content to index
1656         content = self.get(nodeid, 'content')
1657
1658         # figure the mime type
1659         if self.properties.has_key('type'):
1660             mime_type = self.get(nodeid, 'type')
1661         else:
1662             mime_type = self.default_mime_type
1663
1664         # and index!
1665         self.db.indexer.add_text((self.classname, nodeid, 'content'), content,
1666             mime_type)
1667
1668 # XXX deviation from spec - was called ItemClass
1669 class IssueClass(Class, roundupdb.IssueClass):
1670     # Overridden methods:
1671     def __init__(self, db, classname, **properties):
1672         """The newly-created class automatically includes the "messages",
1673         "files", "nosy", and "superseder" properties.  If the 'properties'
1674         dictionary attempts to specify any of these properties or a
1675         "creation" or "activity" property, a ValueError is raised.
1676         """
1677         if not properties.has_key('title'):
1678             properties['title'] = hyperdb.String(indexme='yes')
1679         if not properties.has_key('messages'):
1680             properties['messages'] = hyperdb.Multilink("msg")
1681         if not properties.has_key('files'):
1682             properties['files'] = hyperdb.Multilink("file")
1683         if not properties.has_key('nosy'):
1684             properties['nosy'] = hyperdb.Multilink("user")
1685         if not properties.has_key('superseder'):
1686             properties['superseder'] = hyperdb.Multilink(classname)
1687         Class.__init__(self, db, classname, **properties)
1688
1689 #
1690 #$Log: not supported by cvs2svn $
1691 #Revision 1.48  2002/07/18 11:17:31  gmcm
1692 #Add Number and Boolean types to hyperdb.
1693 #Add conversion cases to web, mail & admin interfaces.
1694 #Add storage/serialization cases to back_anydbm & back_metakit.
1695 #
1696 #Revision 1.47  2002/07/14 23:18:20  richard
1697 #. fixed the journal bloat from multilink changes - we just log the add or
1698 #  remove operations, not the whole list
1699 #
1700 #Revision 1.46  2002/07/14 06:06:34  richard
1701 #Did some old TODOs
1702 #
1703 #Revision 1.45  2002/07/14 04:03:14  richard
1704 #Implemented a switch to disable journalling for a Class. CGI session
1705 #database now uses it.
1706 #
1707 #Revision 1.44  2002/07/14 02:05:53  richard
1708 #. all storage-specific code (ie. backend) is now implemented by the backends
1709 #
1710 #Revision 1.43  2002/07/10 06:30:30  richard
1711 #...except of course it's nice to use valid Python syntax
1712 #
1713 #Revision 1.42  2002/07/10 06:21:38  richard
1714 #Be extra safe
1715 #
1716 #Revision 1.41  2002/07/10 00:21:45  richard
1717 #explicit database closing
1718 #
1719 #Revision 1.40  2002/07/09 04:19:09  richard
1720 #Added reindex command to roundup-admin.
1721 #Fixed reindex on first access.
1722 #Also fixed reindexing of entries that change.
1723 #
1724 #Revision 1.39  2002/07/09 03:02:52  richard
1725 #More indexer work:
1726 #- all String properties may now be indexed too. Currently there's a bit of
1727 #  "issue" specific code in the actual searching which needs to be
1728 #  addressed. In a nutshell:
1729 #  + pass 'indexme="yes"' as a String() property initialisation arg, eg:
1730 #        file = FileClass(db, "file", name=String(), type=String(),
1731 #            comment=String(indexme="yes"))
1732 #  + the comment will then be indexed and be searchable, with the results
1733 #    related back to the issue that the file is linked to
1734 #- as a result of this work, the FileClass has a default MIME type that may
1735 #  be overridden in a subclass, or by the use of a "type" property as is
1736 #  done in the default templates.
1737 #- the regeneration of the indexes (if necessary) is done once the schema is
1738 #  set up in the dbinit.
1739 #
1740 #Revision 1.38  2002/07/08 06:58:15  richard
1741 #cleaned up the indexer code:
1742 # - it splits more words out (much simpler, faster splitter)
1743 # - removed code we'll never use (roundup.roundup_indexer has the full
1744 #   implementation, and replaces roundup.indexer)
1745 # - only index text/plain and rfc822/message (ideas for other text formats to
1746 #   index are welcome)
1747 # - added simple unit test for indexer. Needs more tests for regression.
1748 #
1749 #Revision 1.37  2002/06/20 23:52:35  richard
1750 #More informative error message
1751 #
1752 #Revision 1.36  2002/06/19 03:07:19  richard
1753 #Moved the file storage commit into blobfiles where it belongs.
1754 #
1755 #Revision 1.35  2002/05/25 07:16:24  rochecompaan
1756 #Merged search_indexing-branch with HEAD
1757 #
1758 #Revision 1.34  2002/05/15 06:21:21  richard
1759 # . node caching now works, and gives a small boost in performance
1760 #
1761 #As a part of this, I cleaned up the DEBUG output and implemented TRACE
1762 #output (HYPERDBTRACE='file to trace to') with checkpoints at the start of
1763 #CGI requests. Run roundup with python -O to skip all the DEBUG/TRACE stuff
1764 #(using if __debug__ which is compiled out with -O)
1765 #
1766 #Revision 1.33  2002/04/24 10:38:26  rochecompaan
1767 #All database files are now created group readable and writable.
1768 #
1769 #Revision 1.32  2002/04/15 23:25:15  richard
1770 #. node ids are now generated from a lockable store - no more race conditions
1771 #
1772 #We're using the portalocker code by Jonathan Feinberg that was contributed
1773 #to the ASPN Python cookbook. This gives us locking across Unix and Windows.
1774 #
1775 #Revision 1.31  2002/04/03 05:54:31  richard
1776 #Fixed serialisation problem by moving the serialisation step out of the
1777 #hyperdb.Class (get, set) into the hyperdb.Database.
1778 #
1779 #Also fixed htmltemplate after the showid changes I made yesterday.
1780 #
1781 #Unit tests for all of the above written.
1782 #
1783 #Revision 1.30.2.1  2002/04/03 11:55:57  rochecompaan
1784 # . Added feature #526730 - search for messages capability
1785 #
1786 #Revision 1.30  2002/02/27 03:40:59  richard
1787 #Ran it through pychecker, made fixes
1788 #
1789 #Revision 1.29  2002/02/25 14:34:31  grubert
1790 # . use blobfiles in back_anydbm which is used in back_bsddb.
1791 #   change test_db as dirlist does not work for subdirectories.
1792 #   ATTENTION: blobfiles now creates subdirectories for files.
1793 #
1794 #Revision 1.28  2002/02/16 09:14:17  richard
1795 # . #514854 ] History: "User" is always ticket creator
1796 #
1797 #Revision 1.27  2002/01/22 07:21:13  richard
1798 #. fixed back_bsddb so it passed the journal tests
1799 #
1800 #... it didn't seem happy using the back_anydbm _open method, which is odd.
1801 #Yet another occurrance of whichdb not being able to recognise older bsddb
1802 #databases. Yadda yadda. Made the HYPERDBDEBUG stuff more sane in the
1803 #process.
1804 #
1805 #Revision 1.26  2002/01/22 05:18:38  rochecompaan
1806 #last_set_entry was referenced before assignment
1807 #
1808 #Revision 1.25  2002/01/22 05:06:08  rochecompaan
1809 #We need to keep the last 'set' entry in the journal to preserve
1810 #information on 'activity' for nodes.
1811 #
1812 #Revision 1.24  2002/01/21 16:33:20  rochecompaan
1813 #You can now use the roundup-admin tool to pack the database
1814 #
1815 #Revision 1.23  2002/01/18 04:32:04  richard
1816 #Rollback was breaking because a message hadn't actually been written to the file. Needs
1817 #more investigation.
1818 #
1819 #Revision 1.22  2002/01/14 02:20:15  richard
1820 # . changed all config accesses so they access either the instance or the
1821 #   config attriubute on the db. This means that all config is obtained from
1822 #   instance_config instead of the mish-mash of classes. This will make
1823 #   switching to a ConfigParser setup easier too, I hope.
1824 #
1825 #At a minimum, this makes migration a _little_ easier (a lot easier in the
1826 #0.5.0 switch, I hope!)
1827 #
1828 #Revision 1.21  2002/01/02 02:31:38  richard
1829 #Sorry for the huge checkin message - I was only intending to implement #496356
1830 #but I found a number of places where things had been broken by transactions:
1831 # . modified ROUNDUPDBSENDMAILDEBUG to be SENDMAILDEBUG and hold a filename
1832 #   for _all_ roundup-generated smtp messages to be sent to.
1833 # . the transaction cache had broken the roundupdb.Class set() reactors
1834 # . newly-created author users in the mailgw weren't being committed to the db
1835 #
1836 #Stuff that made it into CHANGES.txt (ie. the stuff I was actually working
1837 #on when I found that stuff :):
1838 # . #496356 ] Use threading in messages
1839 # . detectors were being registered multiple times
1840 # . added tests for mailgw
1841 # . much better attaching of erroneous messages in the mail gateway
1842 #
1843 #Revision 1.20  2001/12/18 15:30:34  rochecompaan
1844 #Fixed bugs:
1845 # .  Fixed file creation and retrieval in same transaction in anydbm
1846 #    backend
1847 # .  Cgi interface now renders new issue after issue creation
1848 # .  Could not set issue status to resolved through cgi interface
1849 # .  Mail gateway was changing status back to 'chatting' if status was
1850 #    omitted as an argument
1851 #
1852 #Revision 1.19  2001/12/17 03:52:48  richard
1853 #Implemented file store rollback. As a bonus, the hyperdb is now capable of
1854 #storing more than one file per node - if a property name is supplied,
1855 #the file is called designator.property.
1856 #I decided not to migrate the existing files stored over to the new naming
1857 #scheme - the FileClass just doesn't specify the property name.
1858 #
1859 #Revision 1.18  2001/12/16 10:53:38  richard
1860 #take a copy of the node dict so that the subsequent set
1861 #operation doesn't modify the oldvalues structure
1862 #
1863 #Revision 1.17  2001/12/14 23:42:57  richard
1864 #yuck, a gdbm instance tests false :(
1865 #I've left the debugging code in - it should be removed one day if we're ever
1866 #_really_ anal about performace :)
1867 #
1868 #Revision 1.16  2001/12/12 03:23:14  richard
1869 #Cor blimey this anydbm/whichdb stuff is yecchy. Turns out that whichdb
1870 #incorrectly identifies a dbm file as a dbhash file on my system. This has
1871 #been submitted to the python bug tracker as issue #491888:
1872 #https://sourceforge.net/tracker/index.php?func=detail&aid=491888&group_id=5470&atid=105470
1873 #
1874 #Revision 1.15  2001/12/12 02:30:51  richard
1875 #I fixed the problems with people whose anydbm was using the dbm module at the
1876 #backend. It turns out the dbm module modifies the file name to append ".db"
1877 #and my check to determine if we're opening an existing or new db just
1878 #tested os.path.exists() on the filename. Well, no longer! We now perform a
1879 #much better check _and_ cope with the anydbm implementation module changing
1880 #too!
1881 #I also fixed the backends __init__ so only ImportError is squashed.
1882 #
1883 #Revision 1.14  2001/12/10 22:20:01  richard
1884 #Enabled transaction support in the bsddb backend. It uses the anydbm code
1885 #where possible, only replacing methods where the db is opened (it uses the
1886 #btree opener specifically.)
1887 #Also cleaned up some change note generation.
1888 #Made the backends package work with pydoc too.
1889 #
1890 #Revision 1.13  2001/12/02 05:06:16  richard
1891 #. We now use weakrefs in the Classes to keep the database reference, so
1892 #  the close() method on the database is no longer needed.
1893 #  I bumped the minimum python requirement up to 2.1 accordingly.
1894 #. #487480 ] roundup-server
1895 #. #487476 ] INSTALL.txt
1896 #
1897 #I also cleaned up the change message / post-edit stuff in the cgi client.
1898 #There's now a clearly marked "TODO: append the change note" where I believe
1899 #the change note should be added there. The "changes" list will obviously
1900 #have to be modified to be a dict of the changes, or somesuch.
1901 #
1902 #More testing needed.
1903 #
1904 #Revision 1.12  2001/12/01 07:17:50  richard
1905 #. We now have basic transaction support! Information is only written to
1906 #  the database when the commit() method is called. Only the anydbm
1907 #  backend is modified in this way - neither of the bsddb backends have been.
1908 #  The mail, admin and cgi interfaces all use commit (except the admin tool
1909 #  doesn't have a commit command, so interactive users can't commit...)
1910 #. Fixed login/registration forwarding the user to the right page (or not,
1911 #  on a failure)
1912 #
1913 #Revision 1.11  2001/11/21 02:34:18  richard
1914 #Added a target version field to the extended issue schema
1915 #
1916 #Revision 1.10  2001/10/09 23:58:10  richard
1917 #Moved the data stringification up into the hyperdb.Class class' get, set
1918 #and create methods. This means that the data is also stringified for the
1919 #journal call, and removes duplication of code from the backends. The
1920 #backend code now only sees strings.
1921 #
1922 #Revision 1.9  2001/10/09 07:25:59  richard
1923 #Added the Password property type. See "pydoc roundup.password" for
1924 #implementation details. Have updated some of the documentation too.
1925 #
1926 #Revision 1.8  2001/09/29 13:27:00  richard
1927 #CGI interfaces now spit up a top-level index of all the instances they can
1928 #serve.
1929 #
1930 #Revision 1.7  2001/08/12 06:32:36  richard
1931 #using isinstance(blah, Foo) now instead of isFooType
1932 #
1933 #Revision 1.6  2001/08/07 00:24:42  richard
1934 #stupid typo
1935 #
1936 #Revision 1.5  2001/08/07 00:15:51  richard
1937 #Added the copyright/license notice to (nearly) all files at request of
1938 #Bizar Software.
1939 #
1940 #Revision 1.4  2001/07/30 01:41:36  richard
1941 #Makes schema changes mucho easier.
1942 #
1943 #Revision 1.3  2001/07/25 01:23:07  richard
1944 #Added the Roundup spec to the new documentation directory.
1945 #
1946 #Revision 1.2  2001/07/23 08:20:44  richard
1947 #Moved over to using marshal in the bsddb and anydbm backends.
1948 #roundup-admin now has a "freshen" command that'll load/save all nodes (not
1949 # retired - mod hyperdb.Class.list() so it lists retired nodes)
1950 #
1951 #