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 $
20 """
21 Hyperdatabase implementation, especially field types.
22 """
24 # standard python modules
25 import sys, os, time, re
27 # roundup modules
28 import date, password
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
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__
65 class Password:
66 """An object designating a Password property."""
67 def __repr__(self):
68 ' more useful for dumps '
69 return '<%s>'%self.__class__
71 class Date:
72 """An object designating a Date property."""
73 def __repr__(self):
74 ' more useful for dumps '
75 return '<%s>'%self.__class__
77 class Interval:
78 """An object designating an Interval property."""
79 def __repr__(self):
80 ' more useful for dumps '
81 return '<%s>'%self.__class__
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)
95 class Multilink:
96 """An object designating a Multilink property that links
97 to nodes in a specified class.
99 "classname" indicates the class to link to
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)
113 class Boolean:
114 """An object designating a boolean property"""
115 def __repr__(self):
116 'more useful for dumps'
117 return '<%s>' % self.__class__
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)
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.
147 This class defines a hyperdatabase storage layer, which the Classes use to
148 store their data.
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.
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.
163 Implementation
164 --------------
166 All methods except __repr__ and getnode must be implemented by a
167 concrete backend Class.
169 '''
171 # flag to set on retired entries
172 RETIRED_FLAG = '__hyperdb_retired'
174 def __init__(self, config, journaltag=None):
175 """Open a hyperdatabase given a specifier to some storage.
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.
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
190 def post_init(self):
191 """Called once the schema initialisation has finished."""
192 raise NotImplementedError
194 def __getattr__(self, classname):
195 """A convenient way of calling self.getclass(classname)."""
196 raise NotImplementedError
198 def addclass(self, cl):
199 '''Add a Class to the hyperdatabase.
200 '''
201 raise NotImplementedError
203 def getclasses(self):
204 """Return a list of the names of all existing classes."""
205 raise NotImplementedError
207 def getclass(self, classname):
208 """Get the Class object representing a particular class.
210 If 'classname' is not a valid class name, a KeyError is raised.
211 """
212 raise NotImplementedError
214 def clear(self):
215 '''Delete all database contents.
216 '''
217 raise NotImplementedError
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
225 def addnode(self, classname, nodeid, node):
226 '''Add the specified node to its class's db.
227 '''
228 raise NotImplementedError
230 def serialise(self, classname, node):
231 '''Copy the node contents, converting non-marshallable data into
232 marshallable data.
233 '''
234 return node
236 def setnode(self, classname, nodeid, node):
237 '''Change the specified node.
238 '''
239 raise NotImplementedError
241 def unserialise(self, classname, node):
242 '''Decode the marshalled node data
243 '''
244 return node
246 def getnode(self, classname, nodeid, db=None, cache=1):
247 '''Get a node from the database.
248 '''
249 raise NotImplementedError
251 def hasnode(self, classname, nodeid, db=None):
252 '''Determine if the database has a given node.
253 '''
254 raise NotImplementedError
256 def countnodes(self, classname, db=None):
257 '''Count the number of nodes that exist for a particular Class.
258 '''
259 raise NotImplementedError
261 def getnodeids(self, classname, db=None):
262 '''Retrieve all the ids of the nodes for a particular Class.
263 '''
264 raise NotImplementedError
266 def storefile(self, classname, nodeid, property, content):
267 '''Store the content of the file in the database.
269 The property may be None, in which case the filename does not
270 indicate which property is being saved.
271 '''
272 raise NotImplementedError
274 def getfile(self, classname, nodeid, property):
275 '''Store the content of the file in the database.
276 '''
277 raise NotImplementedError
279 def addjournal(self, classname, nodeid, action, params):
280 ''' Journal the Action
281 'action' may be:
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
289 def getjournal(self, classname, nodeid):
290 ''' get the journal for id
291 '''
292 raise NotImplementedError
294 def pack(self, pack_before):
295 ''' pack the database
296 '''
297 raise NotImplementedError
299 def commit(self):
300 ''' Commit the current transactions.
302 Save all data changed since the database was opened or since the
303 last commit() or rollback().
304 '''
305 raise NotImplementedError
307 def rollback(self):
308 ''' Reverse all actions from the current transaction.
310 Undo all the changes made since the database was opened or the last
311 commit() or rollback() was performed.
312 '''
313 raise NotImplementedError
315 #
316 # The base Class class
317 #
318 class Class:
319 """ The handle to a particular class of nodes in a hyperdatabase.
321 All methods except __repr__ and getnode must be implemented by a
322 concrete backend Class.
323 """
325 def __init__(self, db, classname, **properties):
326 """Create a new class with a given name and property specification.
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
334 def __repr__(self):
335 '''Slightly more useful representation
336 '''
337 return '<hyperdb.Class "%s">'%self.classname
339 # Editing nodes:
341 def create(self, **propvalues):
342 """Create a new node of this class and return its id.
344 The keyword arguments in 'propvalues' map property names to values.
346 The values of arguments must be acceptable for the types of their
347 corresponding properties or a TypeError is raised.
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.
352 Any other properties on this class that are missing from the
353 'propvalues' dictionary are set to None.
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
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.
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.
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
375 def getnode(self, nodeid, cache=1):
376 ''' Return a convenience wrapper for the node.
378 'nodeid' must be the id of an existing node of this class or an
379 IndexError is raised.
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)
388 def set(self, nodeid, **propvalues):
389 """Modify a property on an existing node of this class.
391 'nodeid' must be the id of an existing node of this class or an
392 IndexError is raised.
394 Each key in 'propvalues' must be the name of a property of this
395 class or a KeyError is raised.
397 All values in 'propvalues' must be acceptable types for their
398 corresponding properties or a TypeError is raised.
400 If the value of the key property is set, it must not collide with
401 other key strings or a ValueError is raised.
403 If the value of a Link or Multilink property contains an invalid
404 node id, a ValueError is raised.
405 """
406 raise NotImplementedError
408 def retire(self, nodeid):
409 """Retire a node.
411 The properties on the node remain available from the get() method,
412 and the node's id is never reused.
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
419 def restore(self, nodeid):
420 '''Restpre a retired node.
422 Make node available for all operations like it was before retirement.
423 '''
424 raise NotImplementedError
426 def is_retired(self, nodeid):
427 '''Return true if the node is rerired
428 '''
429 raise NotImplementedError
431 def destroy(self, nodeid):
432 """Destroy a node.
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
441 Well, I think that's enough warnings. This method exists mostly to
442 support the session storage of the cgi interface.
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 """
449 def history(self, nodeid):
450 """Retrieve the journal of edits on a particular node.
452 'nodeid' must be the id of an existing node of this class or an
453 IndexError is raised.
455 The returned list contains tuples of the form
457 (date, tag, action, params)
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
464 # Locating nodes:
465 def hasnode(self, nodeid):
466 '''Determine if the given nodeid actually exists
467 '''
468 raise NotImplementedError
470 def setkey(self, propname):
471 """Select a String property of this class to be the key property.
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
479 def getkey(self):
480 """Return the name of the key property for this class or None."""
481 raise NotImplementedError
483 def labelprop(self, default_to_id=0):
484 ''' Return the property name for a label for the given node.
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
495 def lookup(self, keyvalue):
496 """Locate a particular node by its key property and return its id.
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
505 def find(self, **propspec):
506 """Get the ids of nodes in this class which link to the given nodes.
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.
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:
518 db.issue.find(messages={'1':1,'3':1}, files={'7':1})
519 """
520 raise NotImplementedError
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.
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}
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
539 def count(self):
540 """Get the number of nodes in this class.
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
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
556 def addprop(self, **properties):
557 """Add properties to this class.
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
566 def index(self, nodeid):
567 '''Add (or refresh) the node to search indexes
568 '''
569 raise NotImplementedError
571 class FileClass:
572 ''' A class that requires the "content" property and stores it on
573 disk.
574 '''
575 pass
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)
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)
637 # vim: set filetype=python ts=4 sw=4 et si