roundup/hyperdb.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: hyperdb.py,v 1.87 2003-03-17 22:03:03 kedder Exp $
  19
  20 """
  21 Hyperdatabase implementation, especially field types.
  22 """
  23
  24 # standard python modules
  25 import sys, os, time, re
  26
  27 # roundup modules
  28 import date, password
  29
  30 # configure up the DEBUG and TRACE captures
  31 class Sink:
  32     def write(self, content):
  33         pass
  34 DEBUG = os.environ.get('HYPERDBDEBUG', '')
  35 if DEBUG and __debug__:
  36     if DEBUG == 'stdout':
  37         DEBUG = sys.stdout
  38     else:
  39         DEBUG = open(DEBUG, 'a')
  40 else:
  41     DEBUG = Sink()
  42 TRACE = os.environ.get('HYPERDBTRACE', '')
  43 if TRACE and __debug__:
  44     if TRACE == 'stdout':
  45         TRACE = sys.stdout
  46     else:
  47         TRACE = open(TRACE, 'w')
  48 else:
  49     TRACE = Sink()
  50 def traceMark():
  51     print >>TRACE, '**MARK', time.ctime()
  52 del Sink
  53
  54 #
  55 # Types
  56 #
  57 class String:
  58     """An object designating a String property."""
  59     def __init__(self, indexme='no'):
  60         self.indexme = indexme == 'yes'
  61     def __repr__(self):
  62         ' more useful for dumps '
  63         return '<%s>'%self.__class__
  64
  65 class Password:
  66     """An object designating a Password property."""
  67     def __repr__(self):
  68         ' more useful for dumps '
  69         return '<%s>'%self.__class__
  70
  71 class Date:
  72     """An object designating a Date property."""
  73     def __repr__(self):
  74         ' more useful for dumps '
  75         return '<%s>'%self.__class__
  76
  77 class Interval:
  78     """An object designating an Interval property."""
  79     def __repr__(self):
  80         ' more useful for dumps '
  81         return '<%s>'%self.__class__
  82
  83 class Link:
  84     """An object designating a Link property that links to a
  85        node in a specified class."""
  86     def __init__(self, classname, do_journal='yes'):
  87         ''' Default is to not journal link and unlink events
  88         '''
  89         self.classname = classname
  90         self.do_journal = do_journal == 'yes'
  91     def __repr__(self):
  92         ' more useful for dumps '
  93         return '<%s to "%s">'%(self.__class__, self.classname)
  94
  95 class Multilink:
  96     """An object designating a Multilink property that links
  97        to nodes in a specified class.
  98
  99        "classname" indicates the class to link to
 100
 101        "do_journal" indicates whether the linked-to nodes should have
 102                     'link' and 'unlink' events placed in their journal
 103     """
 104     def __init__(self, classname, do_journal='yes'):
 105         ''' Default is to not journal link and unlink events
 106         '''
 107         self.classname = classname
 108         self.do_journal = do_journal == 'yes'
 109     def __repr__(self):
 110         ' more useful for dumps '
 111         return '<%s to "%s">'%(self.__class__, self.classname)
 112
 113 class Boolean:
 114     """An object designating a boolean property"""
 115     def __repr__(self):
 116         'more useful for dumps'
 117         return '<%s>' % self.__class__
 118
 119 class Number:
 120     """An object designating a numeric property"""
 121     def __repr__(self):
 122         'more useful for dumps'
 123         return '<%s>' % self.__class__
 124 #
 125 # Support for splitting designators
 126 #
 127 class DesignatorError(ValueError):
 128     pass
 129 def splitDesignator(designator, dre=re.compile(r'([^\d]+)(\d+)')):
 130     ''' Take a foo123 and return ('foo', 123)
 131     '''
 132     m = dre.match(designator)
 133     if m is None:
 134         raise DesignatorError, '"%s" not a node designator'%designator
 135     return m.group(1), m.group(2)
 136
 137 #
 138 # the base Database class
 139 #
 140 class DatabaseError(ValueError):
 141     '''Error to be raised when there is some problem in the database code
 142     '''
 143     pass
 144 class Database:
 145     '''A database for storing records containing flexible data types.
 146
 147 This class defines a hyperdatabase storage layer, which the Classes use to
 148 store their data.
 149
 150
 151 Transactions
 152 ------------
 153 The Database should support transactions through the commit() and
 154 rollback() methods. All other Database methods should be transaction-aware,
 155 using data from the current transaction before looking up the database.
 156
 157 An implementation must provide an override for the get() method so that the
 158 in-database value is returned in preference to the in-transaction value.
 159 This is necessary to determine if any values have changed during a
 160 transaction.
 161
 162
 163 Implementation
 164 --------------
 165
 166 All methods except __repr__ and getnode must be implemented by a
 167 concrete backend Class.
 168
 169 '''
 170
 171     # flag to set on retired entries
 172     RETIRED_FLAG = '__hyperdb_retired'
 173
 174     def __init__(self, config, journaltag=None):
 175         """Open a hyperdatabase given a specifier to some storage.
 176
 177         The 'storagelocator' is obtained from config.DATABASE.
 178         The meaning of 'storagelocator' depends on the particular
 179         implementation of the hyperdatabase.  It could be a file name,
 180         a directory path, a socket descriptor for a connection to a
 181         database over the network, etc.
 182
 183         The 'journaltag' is a token that will be attached to the journal
 184         entries for any edits done on the database.  If 'journaltag' is
 185         None, the database is opened in read-only mode: the Class.create(),
 186         Class.set(), and Class.retire() methods are disabled.
 187         """
 188         raise NotImplementedError
 189
 190     def post_init(self):
 191         """Called once the schema initialisation has finished."""
 192         raise NotImplementedError
 193
 194     def __getattr__(self, classname):
 195         """A convenient way of calling self.getclass(classname)."""
 196         raise NotImplementedError
 197
 198     def addclass(self, cl):
 199         '''Add a Class to the hyperdatabase.
 200         '''
 201         raise NotImplementedError
 202
 203     def getclasses(self):
 204         """Return a list of the names of all existing classes."""
 205         raise NotImplementedError
 206
 207     def getclass(self, classname):
 208         """Get the Class object representing a particular class.
 209
 210         If 'classname' is not a valid class name, a KeyError is raised.
 211         """
 212         raise NotImplementedError
 213
 214     def clear(self):
 215         '''Delete all database contents.
 216         '''
 217         raise NotImplementedError
 218
 219     def getclassdb(self, classname, mode='r'):
 220         '''Obtain a connection to the class db that will be used for
 221            multiple actions.
 222         '''
 223         raise NotImplementedError
 224
 225     def addnode(self, classname, nodeid, node):
 226         '''Add the specified node to its class's db.
 227         '''
 228         raise NotImplementedError
 229
 230     def serialise(self, classname, node):
 231         '''Copy the node contents, converting non-marshallable data into
 232            marshallable data.
 233         '''
 234         return node
 235
 236     def setnode(self, classname, nodeid, node):
 237         '''Change the specified node.
 238         '''
 239         raise NotImplementedError
 240
 241     def unserialise(self, classname, node):
 242         '''Decode the marshalled node data
 243         '''
 244         return node
 245
 246     def getnode(self, classname, nodeid, db=None, cache=1):
 247         '''Get a node from the database.
 248         '''
 249         raise NotImplementedError
 250
 251     def hasnode(self, classname, nodeid, db=None):
 252         '''Determine if the database has a given node.
 253         '''
 254         raise NotImplementedError
 255
 256     def countnodes(self, classname, db=None):
 257         '''Count the number of nodes that exist for a particular Class.
 258         '''
 259         raise NotImplementedError
 260
 261     def getnodeids(self, classname, db=None):
 262         '''Retrieve all the ids of the nodes for a particular Class.
 263         '''
 264         raise NotImplementedError
 265
 266     def storefile(self, classname, nodeid, property, content):
 267         '''Store the content of the file in the database.
 268
 269            The property may be None, in which case the filename does not
 270            indicate which property is being saved.
 271         '''
 272         raise NotImplementedError
 273
 274     def getfile(self, classname, nodeid, property):
 275         '''Store the content of the file in the database.
 276         '''
 277         raise NotImplementedError
 278
 279     def addjournal(self, classname, nodeid, action, params):
 280         ''' Journal the Action
 281         'action' may be:
 282
 283             'create' or 'set' -- 'params' is a dictionary of property values
 284             'link' or 'unlink' -- 'params' is (classname, nodeid, propname)
 285             'retire' -- 'params' is None
 286         '''
 287         raise NotImplementedError
 288
 289     def getjournal(self, classname, nodeid):
 290         ''' get the journal for id
 291         '''
 292         raise NotImplementedError
 293
 294     def pack(self, pack_before):
 295         ''' pack the database
 296         '''
 297         raise NotImplementedError
 298
 299     def commit(self):
 300         ''' Commit the current transactions.
 301
 302         Save all data changed since the database was opened or since the
 303         last commit() or rollback().
 304         '''
 305         raise NotImplementedError
 306
 307     def rollback(self):
 308         ''' Reverse all actions from the current transaction.
 309
 310         Undo all the changes made since the database was opened or the last
 311         commit() or rollback() was performed.
 312         '''
 313         raise NotImplementedError
 314
 315 #
 316 # The base Class class
 317 #
 318 class Class:
 319     """ The handle to a particular class of nodes in a hyperdatabase.
 320
 321         All methods except __repr__ and getnode must be implemented by a
 322         concrete backend Class.
 323     """
 324
 325     def __init__(self, db, classname, **properties):
 326         """Create a new class with a given name and property specification.
 327
 328         'classname' must not collide with the name of an existing class,
 329         or a ValueError is raised.  The keyword arguments in 'properties'
 330         must map names to property objects, or a TypeError is raised.
 331         """
 332         raise NotImplementedError
 333
 334     def __repr__(self):
 335         '''Slightly more useful representation
 336         '''
 337         return '<hyperdb.Class "%s">'%self.classname
 338
 339     # Editing nodes:
 340
 341     def create(self, **propvalues):
 342         """Create a new node of this class and return its id.
 343
 344         The keyword arguments in 'propvalues' map property names to values.
 345
 346         The values of arguments must be acceptable for the types of their
 347         corresponding properties or a TypeError is raised.
 348
 349         If this class has a key property, it must be present and its value
 350         must not collide with other key strings or a ValueError is raised.
 351
 352         Any other properties on this class that are missing from the
 353         'propvalues' dictionary are set to None.
 354
 355         If an id in a link or multilink property does not refer to a valid
 356         node, an IndexError is raised.
 357         """
 358         raise NotImplementedError
 359
 360     _marker = []
 361     def get(self, nodeid, propname, default=_marker, cache=1):
 362         """Get the value of a property on an existing node of this class.
 363
 364         'nodeid' must be the id of an existing node of this class or an
 365         IndexError is raised.  'propname' must be the name of a property
 366         of this class or a KeyError is raised.
 367
 368         'cache' indicates whether the transaction cache should be queried
 369         for the node. If the node has been modified and you need to
 370         determine what its values prior to modification are, you need to
 371         set cache=0.
 372         """
 373         raise NotImplementedError
 374
 375     def getnode(self, nodeid, cache=1):
 376         ''' Return a convenience wrapper for the node.
 377
 378         'nodeid' must be the id of an existing node of this class or an
 379         IndexError is raised.
 380
 381         'cache' indicates whether the transaction cache should be queried
 382         for the node. If the node has been modified and you need to
 383         determine what its values prior to modification are, you need to
 384         set cache=0.
 385         '''
 386         return Node(self, nodeid, cache=cache)
 387
 388     def set(self, nodeid, **propvalues):
 389         """Modify a property on an existing node of this class.
 390
 391         'nodeid' must be the id of an existing node of this class or an
 392         IndexError is raised.
 393
 394         Each key in 'propvalues' must be the name of a property of this
 395         class or a KeyError is raised.
 396
 397         All values in 'propvalues' must be acceptable types for their
 398         corresponding properties or a TypeError is raised.
 399
 400         If the value of the key property is set, it must not collide with
 401         other key strings or a ValueError is raised.
 402
 403         If the value of a Link or Multilink property contains an invalid
 404         node id, a ValueError is raised.
 405         """
 406         raise NotImplementedError
 407
 408     def retire(self, nodeid):
 409         """Retire a node.
 410
 411         The properties on the node remain available from the get() method,
 412         and the node's id is never reused.
 413
 414         Retired nodes are not returned by the find(), list(), or lookup()
 415         methods, and other nodes may reuse the values of their key properties.
 416         """
 417         raise NotImplementedError
 418
 419     def restore(self, nodeid):
 420         '''Restpre a retired node.
 421
 422         Make node available for all operations like it was before retirement.
 423         '''
 424         raise NotImplementedError
 425
 426     def is_retired(self, nodeid):
 427         '''Return true if the node is rerired
 428         '''
 429         raise NotImplementedError
 430
 431     def destroy(self, nodeid):
 432         """Destroy a node.
 433
 434         WARNING: this method should never be used except in extremely rare
 435                  situations where there could never be links to the node being
 436                  deleted
 437         WARNING: use retire() instead
 438         WARNING: the properties of this node will not be available ever again
 439         WARNING: really, use retire() instead
 440
 441         Well, I think that's enough warnings. This method exists mostly to
 442         support the session storage of the cgi interface.
 443
 444         The node is completely removed from the hyperdb, including all journal
 445         entries. It will no longer be available, and will generally break code
 446         if there are any references to the node.
 447         """
 448
 449     def history(self, nodeid):
 450         """Retrieve the journal of edits on a particular node.
 451
 452         'nodeid' must be the id of an existing node of this class or an
 453         IndexError is raised.
 454
 455         The returned list contains tuples of the form
 456
 457             (date, tag, action, params)
 458
 459         'date' is a Timestamp object specifying the time of the change and
 460         'tag' is the journaltag specified when the database was opened.
 461         """
 462         raise NotImplementedError
 463
 464     # Locating nodes:
 465     def hasnode(self, nodeid):
 466         '''Determine if the given nodeid actually exists
 467         '''
 468         raise NotImplementedError
 469
 470     def setkey(self, propname):
 471         """Select a String property of this class to be the key property.
 472
 473         'propname' must be the name of a String property of this class or
 474         None, or a TypeError is raised.  The values of the key property on
 475         all existing nodes must be unique or a ValueError is raised.
 476         """
 477         raise NotImplementedError
 478
 479     def getkey(self):
 480         """Return the name of the key property for this class or None."""
 481         raise NotImplementedError
 482
 483     def labelprop(self, default_to_id=0):
 484         ''' Return the property name for a label for the given node.
 485
 486         This method attempts to generate a consistent label for the node.
 487         It tries the following in order:
 488             1. key property
 489             2. "name" property
 490             3. "title" property
 491             4. first property from the sorted property name list
 492         '''
 493         raise NotImplementedError
 494
 495     def lookup(self, keyvalue):
 496         """Locate a particular node by its key property and return its id.
 497
 498         If this class has no key property, a TypeError is raised.  If the
 499         'keyvalue' matches one of the values for the key property among
 500         the nodes in this class, the matching node's id is returned;
 501         otherwise a KeyError is raised.
 502         """
 503         raise NotImplementedError
 504
 505     def find(self, **propspec):
 506         """Get the ids of nodes in this class which link to the given nodes.
 507
 508         'propspec' consists of keyword args propname={nodeid:1,}
 509         'propname' must be the name of a property in this class, or a
 510         KeyError is raised.  That property must be a Link or Multilink
 511         property, or a TypeError is raised.
 512
 513         Any node in this class whose 'propname' property links to any of the
 514         nodeids will be returned. Used by the full text indexing, which knows
 515         that "foo" occurs in msg1, msg3 and file7, so we have hits on these
 516         issues:
 517
 518             db.issue.find(messages={'1':1,'3':1}, files={'7':1})
 519         """
 520         raise NotImplementedError
 521
 522     def filter(self, search_matches, filterspec, sort=(None,None),
 523             group=(None,None)):
 524         ''' Return a list of the ids of the active nodes in this class that
 525             match the 'filter' spec, sorted by the group spec and then the
 526             sort spec.
 527
 528             "filterspec" is {propname: value(s)}
 529             "sort" and "group" are (dir, prop) where dir is '+', '-' or None
 530                                and prop is a prop name or None
 531             "search_matches" is {nodeid: marker}
 532
 533             The filter must match all properties specificed - but if the
 534             property value to match is a list, any one of the values in the
 535             list may match for that property to match.
 536         '''
 537         raise NotImplementedError
 538
 539     def count(self):
 540         """Get the number of nodes in this class.
 541
 542         If the returned integer is 'numnodes', the ids of all the nodes
 543         in this class run from 1 to numnodes, and numnodes+1 will be the
 544         id of the next node to be created in this class.
 545         """
 546         raise NotImplementedError
 547
 548     # Manipulating properties:
 549     def getprops(self, protected=1):
 550         """Return a dictionary mapping property names to property objects.
 551            If the "protected" flag is true, we include protected properties -
 552            those which may not be modified.
 553         """
 554         raise NotImplementedError
 555
 556     def addprop(self, **properties):
 557         """Add properties to this class.
 558
 559         The keyword arguments in 'properties' must map names to property
 560         objects, or a TypeError is raised.  None of the keys in 'properties'
 561         may collide with the names of existing properties, or a ValueError
 562         is raised before any properties have been added.
 563         """
 564         raise NotImplementedError
 565
 566     def index(self, nodeid):
 567         '''Add (or refresh) the node to search indexes
 568         '''
 569         raise NotImplementedError
 570
 571 class FileClass:
 572     ''' A class that requires the "content" property and stores it on
 573         disk.
 574     '''
 575     pass
 576
 577 class Node:
 578     ''' A convenience wrapper for the given node
 579     '''
 580     def __init__(self, cl, nodeid, cache=1):
 581         self.__dict__['cl'] = cl
 582         self.__dict__['nodeid'] = nodeid
 583         self.__dict__['cache'] = cache
 584     def keys(self, protected=1):
 585         return self.cl.getprops(protected=protected).keys()
 586     def values(self, protected=1):
 587         l = []
 588         for name in self.cl.getprops(protected=protected).keys():
 589             l.append(self.cl.get(self.nodeid, name, cache=self.cache))
 590         return l
 591     def items(self, protected=1):
 592         l = []
 593         for name in self.cl.getprops(protected=protected).keys():
 594             l.append((name, self.cl.get(self.nodeid, name, cache=self.cache)))
 595         return l
 596     def has_key(self, name):
 597         return self.cl.getprops().has_key(name)
 598     def get(self, name, default=None):
 599         if self.has_key(name):
 600             return self[name]
 601         else:
 602             return default
 603     def __getattr__(self, name):
 604         if self.__dict__.has_key(name):
 605             return self.__dict__[name]
 606         try:
 607             return self.cl.get(self.nodeid, name, cache=self.cache)
 608         except KeyError, value:
 609             # we trap this but re-raise it as AttributeError - all other
 610             # exceptions should pass through untrapped
 611             pass
 612         # nope, no such attribute
 613         raise AttributeError, str(value)
 614     def __getitem__(self, name):
 615         return self.cl.get(self.nodeid, name, cache=self.cache)
 616     def __setattr__(self, name, value):
 617         try:
 618             return self.cl.set(self.nodeid, **{name: value})
 619         except KeyError, value:
 620             raise AttributeError, str(value)
 621     def __setitem__(self, name, value):
 622         self.cl.set(self.nodeid, **{name: value})
 623     def history(self):
 624         return self.cl.history(self.nodeid)
 625     def retire(self):
 626         return self.cl.retire(self.nodeid)
 627
 628
 629 def Choice(name, db, *options):
 630     '''Quick helper to create a simple class with choices
 631     '''
 632     cl = Class(db, name, name=String(), order=String())
 633     for i in range(len(options)):
 634         cl.create(name=options[i], order=i)
 635     return hyperdb.Link(name)
 636
 637 # vim: set filetype=python ts=4 sw=4 et si