* src/DateParser.py: documenation enhancements

* src/GrampsBSDDB.py: Add cursor class
* src/GrampsDbBase.py: Add base cursor class
* src/GrampsGEDDB.py: documenation enhancements
* src/GrampsInMemDB.py: Add cursor class
* src/GrampsXMLDB.py: documenation enhancements


svn: r3781

ChangeLog

@@ -1,3 +1,11 @@
+2004-12-05  Don Allingham  <dallingham@users.sourceforge.net>
+	* src/DateParser.py: documenation enhancements
+	* src/GrampsBSDDB.py: Add cursor class
+	* src/GrampsDbBase.py: Add base cursor class
+	* src/GrampsGEDDB.py: documenation enhancements
+	* src/GrampsInMemDB.py: Add cursor class
+	* src/GrampsXMLDB.py: documenation enhancements
+
 2004-12-04  Don Allingham  <dallingham@users.sourceforge.net>
 	* src/ChooseParents.py: use new cursor for interation
 	* src/DbPrompter.py: reformat

src/DateParser.py

@@ -21,8 +21,9 @@
 # $Id$
 
 """
-U.S. English date parsing class. Serves as the base class for any localized
-date parsing class.
+Date parsing class. Serves as the base class for any localized
+date parsing class. The default, base class provides parsing for
+English.
 """
 
 __author__ = "Donald N. Allingham"

src/GrampsBSDDB.py

@@ -20,6 +20,10 @@
 
 # $Id$
 
+"""
+Provides the Berkeley DB (BSDDB) database backend for GRAMPS
+"""
+
 import os
 import time
 import locale
@@ -41,6 +45,20 @@ def find_fidmap(key,data):
 def find_eventname(key,data):
     return str(data[1])
 
+class GrampsBSDDBCursor(GrampsCursor):
+
+    def __init__(self,source):
+        self.cursor = source.cursor()
+        
+    def first(self):
+        return self.cursor.first()
+
+    def next(self):
+        return self.cursor.next()
+
+    def close(self):
+        self.cursor.close()
+
 #-------------------------------------------------------------------------
 #
 # GrampsBSDDB
@@ -61,7 +79,7 @@ class GrampsBSDDB(GrampsDbBase):
         return dbmap
     
     def get_person_cursor(self):
-        return self.person_map.cursor()
+        return GrampsBSDDBCursor(self.person_map)
 
     def load(self,name,callback):
         if self.person_map:

src/GrampsDbBase.py

@@ -32,6 +32,7 @@ from this class.
 #-------------------------------------------------------------------------
 from RelLib import *
 import cPickle
+
 import time
 import locale
 import re
@@ -55,6 +56,50 @@ EVENT_KEY      = 3
 MEDIA_KEY      = 4
 PLACE_KEY      = 5
 
+class GrampsCursor:
+    """
+    Provides a basic iterator that allows the user to cycle through
+    the elements in a particular map. A cursor should never be
+    directly instantiated. Instead, in should be created by the
+    database class.
+
+    A cursor should only be used for a single pass through the
+    database. If multiple passes are needed, multiple cursors
+    should be used.
+    """
+
+    def first(self):
+        """
+        Returns the first (index, data) pair in the database. This
+        should be called before the first call to next(). Note that
+        the data return is in the format of the serialized format
+        stored in the database, not in the more usable class object.
+        The data should be converted to a class using the class's
+        unserialize method.
+
+        If no data is available, None is returned.
+        """
+        return None
+
+    def next(self):
+        """
+        Returns the next (index, data) pair in the database. Like
+        the first() method, the data return is in the format of the
+        serialized format stored in the database, not in the more
+        usable class object. The data should be converted to a class
+        using the class's unserialize method.
+
+        None is returned when no more data is available.
+        """
+        return None
+
+    def close(self):
+        """
+        Closes the cursor. This should be called when the user is
+        finished using the cursor, freeing up the cursor's resources.
+        """
+        pass
+
 class GrampsDbBase:
     """
     GRAMPS database object. This object is a base class for all

src/GrampsGEDDB.py

@@ -20,6 +20,11 @@
 
 # $Id$
 
+"""
+Provides the GRAMPS DB interface for supporting in-memory editing
+of GEDCOM files.
+"""
+
 from RelLib import *
 from GrampsInMemDB import *
 

src/GrampsInMemDB.py

@@ -20,6 +20,11 @@
 
 # $Id$
 
+"""
+Provides the common infrastructure for database formats that
+must hold all of their data in memory.
+"""
+
 from RelLib import *
 from GrampsDbBase import *
 
@@ -28,8 +33,12 @@ import md5
 import gtk
 
 
-class GrampsCursor:
-
+class GrampsInMemCursor(GrampsCursor):
+    """
+    Cursor class for in-memory database classes. Since the in-memory
+    classes use python dictionaries, the python iter class is used
+    to provide the cursor function.
+    """
     def __init__(self,src_map):
         self.src_map = src_map
         self.current = iter(src_map)
@@ -81,7 +90,7 @@ class GrampsInMemDB(GrampsDbBase):
         pass
 
     def get_person_cursor(self):
-        return GrampsCursor(self.person_map)
+        return GrampsInMemCursor(self.person_map)
 
     def close(self):
         pass

src/GrampsXMLDB.py

@@ -20,6 +20,11 @@
 
 # $Id$
 
+"""
+Provides the GRAMPS DB interface for supporting in-memory editing
+of GRAMPS XML format.
+"""
+
 from RelLib import *
 from GrampsInMemDB import *