pdk.DataBaseClasses ($Date: 2002/12/04 10:13:05 $)
index
pdk/DataBaseClasses.py

Provides data base classes for pdk. There are two groups:

  1. XML data base classes, which essentially are fancy DOM trees connected to XML streams for input and output (XmlReadOnlyDataBase and XmlReadWriteDataBase; see pdk.XmlStream module for the XML stream classes)
  2. shelf data base classes (ShelfDataBase and SubTreeShelfDataBase), which provide a simple (single-access) relational data base built from pdk.DataClasses.TableClasses.Table instances living in a shelf file.

XML data base objects support (in addition to the functionality provided by the pdk.DomClasses.PyObjectDomTree base class):

Shelf data base objects support

FOG 05.2000

 
Classes
            
pdk.DomClasses.PyObjectDomTree(pdk.DomClasses.DomTree)
XmlReadOnlyDataBase
XmlReadWriteDataBase
ShelfDataBase
SubTreeShelfDataBase
pdk.ErrorClasses.pdkError(exceptions.StandardError)
XmlReadOnlyDataBaseError
 
class ShelfDataBase
     
Purpose:simple-minded (single-access) shelf-based data base for pdk tables

 
   Methods defined here:
__contains__(self, key)
__del__(self)
__delitem__(self, tableName)
__getitem__(self, tableName)
__init__(self, shelfSource, shelfClass=<class pdk.DataClasses.ShelfClasses.SafeShelf>)
__setitem__(self, tableName, table)
clearCache(self)
close(self)
closes the data base.
commit(self, tableName)
commit the table named %tableName% to the shelf.
commitAll = close(self)
createTable(self, tableName)
implements the creation of a pdk table based on an entry in the DBSTRUCTURE attribute (a data base declaration container object).
declareTable(self, tableName, tableDeclaration)
adds the declarations for the table tableName given in tableDeclaration to the data base declarations.
deleteRecord(self, tableName, indexName, indexValue)
delete the record specified by the index indexName and it`s value indexValue.
getStructure(self, tableName)
returns an empty table of the same structure as the table specified by tableName.
insertRecord(self, tableName, primaryKey, recordData, autoIncrement=1, checkExisting=0)
inserts (i.e., appends) the data in recordData in the table specified by tableName and automatically increments the (numeric) primary key primaryKey, if autoIncrement is set.
isCached(self, tableName)
join(self, leftTable, rightTable, key, mode, columns)
key can either be a string (if the column by which to perform the join has the same name in both tables) or a 2-tuple of strings (containing the names of the column by which to perform the join for the left and the right table, respectively). If not None, columns should be a list of column names specifying a subset of columns to be used from the right table to construct the joined table.
joinInner(self, leftTable, rightTableName, key, columns=None)
perform an inner join of leftTable with the table specified by rightTableName using the key key. For further information on the parameters, see the .join method.
joinLeft(self, leftTable, rightTableName, key, columns=None)
perform a left join of leftTable with the table specified by rightTableName using the key key. For further information on the parameters, see the .join method.
joinRight(self, leftTable, rightTableName, key, columns=None)
perform a right join of leftTable with the table specified by rightTableName using the key key. For further information on the parameters, see the .join method.
keys(self)
returns the names of all tables in the data base. Note that this includes tables which have been added (with the __setitem__ method), but not committed yet.
listTables = keys(self)
selectByKey(self, tableName, keyName, keyValue)
select all records in the table specified by tableName for which the field keyName has the value keyValue.
selectByPrimaryKey(self, tableName, keyName, keyValue)
select the single record in the table specified by tableName for which the field keyName has the value keyValue. If the table has an index "id", it is assumed that this is what we look for. If keyName is a tuple, we do a more elaborate .selectByKey query and check that the result has length 1 (if not, an IndexError is raised). Finally, if keyName is None, the table structure is returned.
selectIndexed(self, tableName, indexName, indexValue, copy=0)
select the record in tableName defined by indexValue for the index indexName.

Data and non-method functions defined here:
DBSTRUCTURE = <DBase "None" with keys: []>
 
class SubTreeShelfDataBase(ShelfDataBase)
     
Purpose:a ShelfDataBase using only a sub-tree in an underlying pdk.DataClasses.ShelfClasses.TreeShelf
Detail:specializes ShelfDataBase to prefix all key accesses to an underlying tree shelf with the tuple key that is provided with the locator argument locator, which is a tuple of the form (<shelf source>,<shelf key tuple>), where <shelf source> is anything accepted by pdk.DataClasses.ShelfClasses.shelf_factory and <shelf key tuple> is a tuple of strings pointing into the underlying tree shelf.

 
   Methods defined here:
__delitem__(self, tableKeyOrName)
__getitem__(self, tableKeyOrName)
__init__(self, locator)
__setitem__(self, tableKeyOrName, value)
declareTable(self, tableKeyOrName, tableDeclaration)
 
class XmlReadOnlyDataBase(pdk.DomClasses.PyObjectDomTree)
     
Purpose:an XML data base connected to a (read-only) input stream
Detail:extends PyObjectDomTree with a connection to an XML input stream. The .synchronizeWithSource method should be called whenever the input stream is modified to update the DOM tree data.

 
  
Method resolution order:
XmlReadOnlyDataBase
pdk.DomClasses.PyObjectDomTree
pdk.DomClasses.DomTree

Methods defined here:
__init__(self, xmlSourceStream, **parseOptionD)
buildFromStream(self, xmlStream, parentNode=None)
calls the base class method using xmlStream, parentNode and the parse option dictionary passed to the constructor as arguments.
fromSource(self)
re-reads and -builds the DOM tree from its associated input stream.
getNode(self, nodeTT, contextNode=None, assertUniquePath=1, findClosestMatchingNode=0)

implements node matching with node matching tuples. The node matching tuple nodeTT has the form

((<node name>, <node value>, <attribute dictionary>), ...),

i.e., it is really a tuple of node specifying tuples.

<node name> matches the tag name of a DOM tree node

<node value> matches the node value (not yet implemented!)

<attribute dictionary> matches the node attributes.

Matching starts with the children of the node given in contextNode (or the root node, if contextNode is None), with the leftmost node specifying tuple, and descends recursively into the DOM tree until the specified node is found or no node matching the next node specifying tuple can be found among the children of the currenly matched node. This case either raises an error or returns the current matching node and the left-over of the node specifying tuple, depending on the setting of the findClosestMatchingNode option.

sourceWasModified(self)
check whether the XML source of the DOM tree has been modified since the last build.
synchronizeWithSource(self)
update the DOM tree from the input stream, if the modification time of the latter has changed since the last update.
toStdout(self, startNode=None)
prints the data base to stdout.
 
class XmlReadOnlyDataBaseError(pdk.ErrorClasses.pdkError)
       
  
Method resolution order:
XmlReadOnlyDataBaseError
pdk.ErrorClasses.pdkError
exceptions.StandardError
exceptions.Exception

Data and non-method functions defined here:
CODES = {'insert_duplicate_id': ('Trying to insert a node with an already existing node ID string.', ''), 'path_not_unique': ('Identical nodes were encountered while following the given DOM path.', '')}
DOMAIN = 'XmlReadOnlyDataBase'
 
class XmlReadWriteDataBase(XmlReadOnlyDataBase)
     
Purpose:an XML data base connected to an input and a storage stream
Detail:augments the interface of XmlReadOnlyDataBase with the capability to write changes made to the DOM tree (via an instance of the DomBuilder class) to the stream-like object xmlStorageStream. Note that changes are not commited until the .close method is called.

 
  
Method resolution order:
XmlReadWriteDataBase
XmlReadOnlyDataBase
pdk.DomClasses.PyObjectDomTree
pdk.DomClasses.DomTree

Methods defined here:
__del__(self)
__init__(self, xmlSourceStream, xmlStorageStream, **parseOptionD)
buildNode(self, nodeTT, contextNode=None, assertUniquePath=1)
build a new node according to the definitions in nodeTT as a child of contextNode. Note that, if necessary, all intermediate nodes are also created. Works by calling .getNode with the "buildRecursive" flag set to True.
close(self)
write the DOM data out to the storage stream and commit the latter.
getNode(self, nodeTT, contextNode=None, assertUniquePath=1, buildRecursive=0)
this extends the base class method with the capability to dynamically create a node on the fly according to the node definitions in nodeTT, if it does not exist. To enable this behavior, switch on buildRecursive.
insert(self, source, parentNode, insertBefore=0, persistent=0)

inserts the content (i.e., the child nodes of the document node) of the database specified by source at the node parentNode into the DOM tree. Only if persistent is true, the change to the data base will be committed to the XML target stream connected to this instance upon exit. For the insertBefore argument, see the buildChildFromNode method of pdk.DomClasses.DomTree.

Notes

  1. each call to .synchronizeWithSource will check not only for modifications of the main tree`s XML source, but also for modifications of any of the sources of these inserted data bases
  2. for the insertion operation to work, all child nodes in the inserted data base have to provide an "id" attribute
  3. source can be anything pdk.XmlStream.prepare_xml_stream can handle
synchronizeWithSource(self)
in addition to the base class method, this checks for modifications in the sources of all inserted data bases, if any. Returns True if the tree was updated in any way, False otherwise.
 
Author
            
$Author: gathmann $