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