#
# $Id$
#
# This file contains class definitions and interface to the database
# itself while defining objects that the database will return.
#

#
# The most generic exception that this library will raise.
#
class PVVDBError(Exception):
    pass


#
# PVVMember is the class that represents a record in the database.
# Its interface is like a dict with a few additional methods to
# talk to the database itself.
#
class PVVMember(dict):

    def __init__(self, data, dbref):
        # Populate the object with the fields and values provided in the
        # `data' object.  `dbref' is a pointer to the PVVDB instance that
        # created the PVVMember instance.
        pass

    def save(self):
        # Synchronise the object to disk via the database interface.
        pass

    def load(self):
        # Update the object with the data on disk.
        pass

    def is_saved(self):
        # Checks whether the objects need to be saved or loaded.
        pass


#
# PVVDB is the class that interfaces to the directory structure and files.
# It also verifies the data read from the files and written to it.
#
class PVVDB:

    def __init__(self, base):
        # Find the record definition file, read it, verify it and
        # set the legal set of fields.
        pass

    def __del__(self):
        # clean up locks and such before being deleted.
        pass

    def lock(self, username):
        # Lock the record.
        pass

    def unlock(self, username):
        # Unlock the record.
        pass

    def load(self, username, lock=False):
        # Read the record from the database.  Will do an automatic lock
        # if `lock' is True.
        pass

    def save(self, username, comment="", lock=False):
        # Write the record to the database.  Will automatically unlock
        # the record if `lock' is True.  A `comment' can be supplied that
        # explains the changes made.
        pass


#
# Regular interface to the database.
#
def connect(path):
    # returns a PVVDB instance to that path.  If asked for another
    # PVVDB instance with the same path as earlier, it will return
    # the same object.
    pass

def disconnect(dbo):
    # do not do anything, really.  PVVDB objects will clean up
    # automatically when deleted.
    pass