Cyclone-Team/gramps
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Tweaks to database objects plus initial documentation in rst format

Browse Source 
svn: r13157
This commit is contained in:
Gerald Britton 2009-09-03 19:44:01 +00:00
parent 939ef94e67
commit ee9f1e82e0
5 changed files with 281 additions and 254 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

36
docs/gen/gen_db.rst
View File

@ -6,4 +6,38 @@ Contents:
.. automodule:: gen.db
**TODO**
*****************************
Base object
*****************************
GrampsDbBase
====================================
.. automodule:: gen.db.base
.. autoclass:: gen.db.base.GrampsDbBase
:members:
:undoc-members:
:show-inheritance:
*****************************
Read object
*****************************
GrampsDbRead
====================================
.. automodule:: gen.db.read
.. autoclass:: gen.db.read.GrampsDbRead
:members:
:show-inheritance:
*****************************
Write object
*****************************
GrampsDbWrite
====================================
.. automodule:: gen.db.write
.. autoclass:: gen.db.write.GrampsDBDir
:members:
:undoc-members:
:show-inheritance:

2
src/gen/db/__init__.py
View File

@ -20,8 +20,8 @@
from base import *
from dbconst import *
from read import *
from cursor import *
from read import *
from bsddbtxn import *
from txn import *
from undoredo import *

332
src/gen/db/base.py
View File

@ -92,55 +92,17 @@ class GrampsDbBase(object):
"""
Return True if database is upgraded
"""
raise NotImplementedError
raise NotImplementedError
def del_person(self, handle):
def set_auto_remove(self):
"""
Delete a Person object given the handle
BSDDB change log settings using new method with renamed attributes
"""
raise NotImplementedError
raise NotImplementedError
def del_source(self, handle):
"""
Delete a Source object given the handle
"""
raise NotImplementedError
def del_repository(self, handle):
"""
Delete a Repository object given the handle
"""
raise NotImplementedError
def del_note(self, handle):
"""
Delete a Person object given the handle
"""
raise NotImplementedError
def del_place(self, handle):
"""
Delete a Place object given the handle
"""
raise NotImplementedError
def del_media(self, handle):
"""
Delete a Media object given the handle
"""
raise NotImplementedError
def del_family(self, handle):
"""
Delete a Family object given the handle
"""
raise NotImplementedError
def del_event(self, handle):
"""
Delete an Event object given the handle
"""
raise NotImplementedError
def write_version(self, name):
"""Write version number for a newly created DB."""
raise NotImplementedError
def create_id(self):
"""
@ -154,93 +116,63 @@ class GrampsDbBase(object):
"""
raise NotImplementedError
def get_person_cursor_iter(self, msg=None):
"""
Return a reference to a cursor iterator over Person objects
"""
raise NotImplementedError
def get_family_cursor(self):
"""
Return a reference to a cursor over Family objects
"""
raise NotImplementedError
def get_family_cursor_iter(self, msg=None):
"""
Return a reference to a cursor iterator over Family objects
"""
raise NotImplementedError
def get_event_cursor(self):
"""
Return a reference to a cursor over Family objects
"""
raise NotImplementedError
def get_event_cursor_iter(self, msg=None):
"""
Return a reference to a cursor iterator over Family objects
"""
raise NotImplementedError
def get_place_cursor(self):
"""
Return a reference to a cursor over Place objects
"""
raise NotImplementedError
def get_place_cursor_iter(self, msg=None):
"""
Return a reference to a cursor iterator over Place objects
"""
raise NotImplementedError
def get_source_cursor(self):
"""
Return a reference to a cursor over Source objects
"""
raise NotImplementedError
def get_source_cursor_iter(self, msg=None):
"""
Return a reference to a cursor iterator over Source objects
"""
raise NotImplementedError
def get_media_cursor(self):
"""
Return a reference to a cursor over Media objects
"""
raise NotImplementedError
def get_media_cursor_iter(self, msg=None):
"""
Return a reference to a cursor iterator over Media objects
"""
raise NotImplementedError
def get_repository_cursor(self):
"""
Return a reference to a cursor over Repository objects
"""
raise NotImplementedError
def get_repository_cursor_iter(self, msg=None):
"""
Return a reference to a cursor iterator over Repository objects
"""
raise NotImplementedError
def get_note_cursor(self):
"""
Return a reference to a cursor over Note objects
"""
raise NotImplementedError
def get_note_cursor_iter(self, msg=None):
def get_reference_map_cursor(self):
"""
Return a reference to a cursor iterator over Note objects
Returns a reference to a cursor over the reference map
"""
raise NotImplementedError
def get_reference_map_primary_cursor(self):
"""
Returns a reference to a cursor over the reference map primary map
"""
raise NotImplementedError
def get_reference_map_referenced_cursor(self):
"""
Returns a reference to a cursor over the reference map referenced map
"""
raise NotImplementedError
@ -293,8 +225,7 @@ class GrampsDbBase(object):
"""
raise NotImplementedError
def commit_base(self, obj, data_map, key, update_list, add_list,
transaction, change_time):
def commit_base(self, obj, data_map, key, transaction, change_time):
"""
Commit the specified object to the database, storing the changes as
part of the transaction.
@ -504,9 +435,9 @@ class GrampsDbBase(object):
If no object exists, a new object is added to the database.
@return: Returns a tuple, first the object, second a bool which is True
:returns: Returns a tuple, first the object, second a bool which is True
if the object is new
@rtype: tuple
"""
raise NotImplementedError
@ -516,9 +447,9 @@ class GrampsDbBase(object):
If no such Person exists, a new Person is added to the database.
@return: Returns a tuple, first the object, second a bool which is True
:returns: Returns a tuple, first the object, second a bool which is True
if the object is new
@rtype: tuple
"""
raise NotImplementedError
@ -528,9 +459,9 @@ class GrampsDbBase(object):
If no such Source exists, a new Source is added to the database.
@return: Returns a tuple, first the object, second a bool which is True
:returns: Returns a tuple, first the object, second a bool which is True
if the object is new
@rtype: tuple
"""
raise NotImplementedError
@ -539,10 +470,8 @@ class GrampsDbBase(object):
Find a Event in the database from the passed handle.
If no such Event exists, a new Event is added to the database.
@return: Returns a tuple, first the object, second a bool which is True
:returns: Returns a tuple, first the object, second a bool which is True
if the object is new
@rtype: tuple
"""
raise NotImplementedError
@ -552,9 +481,9 @@ class GrampsDbBase(object):
If no such MediaObject exists, a new Object is added to the database.
@return: Returns a tuple, first the object, second a bool which is True
:returns: Returns a tuple, first the object, second a bool which is True
if the object is new
@rtype: tuple
"""
raise NotImplementedError
@ -564,9 +493,9 @@ class GrampsDbBase(object):
If no such Place exists, a new Place is added to the database.
@return: Returns a tuple, first the object, second a bool which is True
:returns: Returns a tuple, first the object, second a bool which is True
if the object is new
@rtype: tuple
"""
raise NotImplementedError
@ -576,9 +505,9 @@ class GrampsDbBase(object):
If no such Family exists, a new Family is added to the database.
@return: Returns a tuple, first the object, second a bool which is True
:returns: Returns a tuple, first the object, second a bool which is True
if the object is new
@rtype: tuple
"""
raise NotImplementedError
@ -588,9 +517,9 @@ class GrampsDbBase(object):
If no such Repository exists, a new Repository is added to the database.
@return: Returns a tuple, first the object, second a bool which is True
:returns: Returns a tuple, first the object, second a bool which is True
if the object is new
@rtype: tuple
"""
raise NotImplementedError
@ -600,9 +529,9 @@ class GrampsDbBase(object):
If no such Note exists, a new Note is added to the database.
@return: Returns a tuple, first the object, second a bool which is True
:returns: Returns a tuple, first the object, second a bool which is True
if the object is new
@rtype: tuple
"""
raise NotImplementedError
@ -927,15 +856,17 @@ class GrampsDbBase(object):
"""
raise NotImplementedError
def iter_person_handles(self):
def get_family_handles(self):
"""
Return an iterator over handles for Persons in the database
Return a list of database handles, one handle for each Family in
the database.
"""
raise NotImplementedError
def iter_people(self):
def get_event_handles(self):
"""
Return an iterator over handles and objects for Persons in the database
Return a list of database handles, one handle for each Event in the
database.
"""
raise NotImplementedError
@ -947,13 +878,7 @@ class GrampsDbBase(object):
If sort_handles is True, the list is sorted by Place title.
"""
raise NotImplementedError
def iter_place_handles(self):
"""
Return an iterator over handles for Places in the database
"""
raise NotImplementedError
def get_source_handles(self, sort_handles=True):
"""
Return a list of database handles, one handle for each Source in
@ -962,13 +887,7 @@ class GrampsDbBase(object):
If sort_handles is True, the list is sorted by Source title.
"""
raise NotImplementedError
def iter_source_handles(self):
"""
Return an iterator over handles for Sources in the database
"""
raise NotImplementedError
def get_media_object_handles(self, sort_handles=True):
"""
Return a list of database handles, one handle for each MediaObject in
@ -977,38 +896,6 @@ class GrampsDbBase(object):
If sort_handles is True, the list is sorted by title.
"""
raise NotImplementedError
def iter_media_object_handles(self):
"""
Return an iterator over handles for Media in the database
"""
raise NotImplementedError
def get_event_handles(self):
"""
Return a list of database handles, one handle for each Event in the
database.
"""
raise NotImplementedError
def iter_event_handles(self):
"""
Return an iterator over handles for Events in the database
"""
raise NotImplementedError
def get_family_handles(self):
"""
Return a list of database handles, one handle for each Family in
the database.
"""
raise NotImplementedError
def iter_family_handles(self):
"""
Return an iterator over handles for Families in the database
"""
raise NotImplementedError
def get_repository_handles(self):
"""
@ -1016,12 +903,6 @@ class GrampsDbBase(object):
the database.
"""
raise NotImplementedError
def iter_repository_handles(self):
"""
Return an iterator over handles for Repositories in the database
"""
raise NotImplementedError
def get_note_handles(self):
"""
@ -1029,6 +910,48 @@ class GrampsDbBase(object):
database.
"""
raise NotImplementedError
def iter_person_handles(self):
"""
Return an iterator over handles for Persons in the database
"""
raise NotImplementedError
def iter_family_handles(self):
"""
Return an iterator over handles for Families in the database
"""
raise NotImplementedError
def iter_event_handles(self):
"""
Return an iterator over handles for Events in the database
"""
raise NotImplementedError
def iter_place_handles(self):
"""
Return an iterator over handles for Places in the database
"""
raise NotImplementedError
def iter_source_handles(self):
"""
Return an iterator over handles for Sources in the database
"""
raise NotImplementedError
def iter_media_object_handles(self):
"""
Return an iterator over handles for Media in the database
"""
raise NotImplementedError
def iter_repository_handles(self):
"""
Return an iterator over handles for Repositories in the database
"""
raise NotImplementedError
def iter_note_handles(self):
"""
@ -1036,6 +959,54 @@ class GrampsDbBase(object):
"""
raise NotImplementedError
def iter_people(self):
"""
Return an iterator over objects for Persons in the database
"""
raise NotImplementedError
def iter_families(self):
"""
Return an iterator over objects for Families in the database
"""
raise NotImplementedError
def iter_events(self):
"""
Return an iterator over objects for Events in the database
"""
raise NotImplementedError
def iter_places(self):
"""
Return an iterator over objects for Places in the database
"""
raise NotImplementedError
def iter_sources(self):
"""
Return an iterator over objects for Sources in the database
"""
raise NotImplementedError
def iter_media_objects(self):
"""
Return an iterator over objects for MediaObjects in the database
"""
raise NotImplementedError
def iter_repositories(self):
"""
Return an iterator over objects for Repositories in the database
"""
raise NotImplementedError
def iter_notes(self):
"""
Return an iterator over objects for Notes in the database
"""
raise NotImplementedError
def get_gramps_ids(self, obj_key):
"""
Returns all the keys from a table given a table name
@ -1552,6 +1523,12 @@ class GrampsDbBase(object):
"""Return the default media path of the database."""
raise NotImplementedError
def set_column_order(self, col_list, name):
"""
Store the display information in the database's metadata.
"""
raise NotImplementedError
def set_person_column_order(self, col_list):
"""
Store the Person display common information in the database's metadata.
@ -1699,23 +1676,24 @@ class GrampsDbBase(object):
Find all objects that hold a reference to the object handle.
Returns an iterator over a list of (class_name, handle) tuples.
@param handle: handle of the object to search for.
@type handle: database handle
@param include_classes: list of class names to include in the results.
Default: None means include all classes.
@type include_classes: list of class names
:param handle: handle of the object to search for.
:type handle: database handle
:param include_classes: list of class names to include in the results.
Default is None which includes all classes.
:type include_classes: list of class names
This default implementation does a sequential scan through all
the primary object databases and is very slow. Backends can
override this method to provide much faster implementations that
make use of additional capabilities of the backend.
Note that this is a generator function, it returns a iterator for
use in loops. If you want a list of the results use:
> result_list = list(find_backlink_handles(handle))
use in loops. If you want a list of the results use::
result_list = list(find_backlink_handles(handle))
"""
raise NotImplementedError
def report_bm_change(self):

102
src/gen/db/read.py
View File

@ -21,7 +21,7 @@
# $Id: read.py 12786 2009-07-11 15:32:37Z gburto01 $
"""
Read class for the GRAMPS databases.
Read classes for the GRAMPS databases.
"""
from __future__ import with_statement
#-------------------------------------------------------------------------
@ -49,9 +49,7 @@ from gen.lib import (MediaObject, Person, Family, Source, Event, Place,
Repository, Note, GenderStats, Researcher)
from gen.db.dbconst import *
from gen.utils.callback import Callback
from gen.db.cursor import GrampsCursor
from gen.db.iterator import CursorIterator
from gen.db.base import GrampsDbBase
from gen.db import (GrampsCursor, GrampsDbBase)
from Utils import create_id
import Errors
@ -107,7 +105,61 @@ class GrampsDbReadCursor(GrampsCursor):
class GrampsDbRead(GrampsDbBase, Callback):
"""
GRAMPS database read access object.
Read class for the GRAMPS databases. Implements methods necessary to read
the various object classes. Currently, there are eight (8) classes:
Person, Family, Event, Place, Source, MediaObject, Repository and Note
For each object class, there are methods to retrieve data in various ways.
In the methods described below, <object> can be one of person, family,
event, place, source, media_object, respository or note unless otherwise
specified.
.. method:: get_<object>_from_handle()
returns an object given its handle
.. method:: get_<object>_from_gramps_id()
returns an object given its gramps id
.. method:: get_<object>_cursor()
returns a cursor over an object. Example use::
with get_person_cursor() as cursor:
for handle, person in cursor:
# process person object pointed to by the handle
.. method:: get_<object>_handles()
returns a list of handles for the object type, optionally sorted
(for Person, Place, Source and Media objects)
.. method:: iter_<object>_handles()
returns an iterator that yields one object handle per call.
.. method:: iter_<objects>()
returns an iterator that yields one object per call.
The objects available are: people, families, events, places,
sources, media_objects, repositories and notes.
.. method:: get_<object>_event_types()
returns a list of all Event types assocated with instances of <object>
in the database.
.. method:: get_<object>_attribute_types()
returns a list of all Event types assocated with instances of <object>
in the database.
.. method:: get_<object>_column_order()
returns the object's display common information.
"""
# This holds a reference to the gramps Config module if
@ -259,30 +311,6 @@ class GrampsDbRead(GrampsDbBase, Callback):
def get_note_cursor(self):
return self.__get_cursor(self.note_map)
def get_person_cursor_iter(self, msg=_("Processing Person records")):
return CursorIterator(self, self.get_person_cursor(), msg)
def get_family_cursor_iter(self, msg=_("Processing Family records")):
return CursorIterator(self, self.get_family_cursor(), msg)
def get_event_cursor_iter(self, msg=_("Processing Event records")):
return CursorIterator(self, self.get_event_cursor(), msg)
def get_place_cursor_iter(self, msg=_("Processing Place records")):
return CursorIterator(self, self.get_place_cursor(), msg)
def get_source_cursor_iter(self, msg=_("Processing Source records")):
return CursorIterator(self, self.get_source_cursor(), msg)
def get_media_cursor_iter(self, msg=_("Processing Media records")):
return CursorIterator(self, self.get_media_cursor(), msg)
def get_repository_cursor_iter(self, msg=_("Processing Repository records")):
return CursorIterator(self, self.get_repository_cursor(), msg)
def get_note_cursor_iter(self, msg=_("Processing Note records")):
return CursorIterator(self, self.get_note_cursor(), msg)
def load(self, name, callback, mode=DBMODE_R):
"""
Open the specified database.
@ -787,6 +815,7 @@ class GrampsDbRead(GrampsDbBase, Callback):
iter_media_object_handles = _f(get_media_cursor)
iter_repository_handles = _f(get_repository_cursor)
iter_note_handles = _f(get_note_cursor)
del _f
def _f(curs_, obj_):
"""
@ -810,6 +839,7 @@ class GrampsDbRead(GrampsDbBase, Callback):
iter_media_objects = _f(get_media_cursor, MediaObject)
iter_repositories = _f(get_repository_cursor, Repository)
iter_notes = _f(get_note_cursor, Note)
del _f
def get_gramps_ids(self, obj_key):
key2table = {
@ -1483,11 +1513,11 @@ class GrampsDbRead(GrampsDbBase, Callback):
Returns an interator over alist of (class_name, handle) tuples.
@param handle: handle of the object to search for.
@type handle: database handle
@param include_classes: list of class names to include in the results.
Default: None means include all classes.
@type include_classes: list of class names
:param handle: handle of the object to search for.
:type handle: database handle
:param include_classes: list of class names to include in the results.
Defaults to None, which includes all classes.
:type include_classes: list of class names
This default implementation does a sequencial scan through all
the primary object databases and is very slow. Backends can
@ -1495,9 +1525,9 @@ class GrampsDbRead(GrampsDbBase, Callback):
make use of additional capabilities of the backend.
Note that this is a generator function, it returns a iterator for
use in loops. If you want a list of the results use:
use in loops. If you want a list of the results use::
> result_list = list(ind_backlink_handles(handle))
result_list = list(find_backlink_handles(handle))
"""
assert False, "read:find_backlink_handles -- shouldn't get here!!!"
# Make a dictionary of the functions and classes that we need for

63
src/gen/db/write.py
View File

@ -249,6 +249,9 @@ class GrampsDBDir(GrampsDbRead, Callback, UpdateCallback):
# the main index is unique, the others allow duplicate entries.
def get_reference_map_cursor(self):
"""
Returns a reference to a cursor over the reference map
"""
try:
return GrampsDBDirAssocCursor(self.reference_map, self.txn)
except DBERRS, msg:
@ -256,6 +259,9 @@ class GrampsDBDir(GrampsDbRead, Callback, UpdateCallback):
raise Errors.DbError(msg)
def get_reference_map_primary_cursor(self):
"""
Returns a reference to a cursor over the reference map primary map
"""
try:
return GrampsDBDirAssocCursor(self.reference_map_primary_map,
self.txn)
@ -264,6 +270,9 @@ class GrampsDBDir(GrampsDbRead, Callback, UpdateCallback):
raise Errors.DbError(msg)
def get_reference_map_referenced_cursor(self):
"""
Returns a reference to a cursor over the reference map referenced map
"""
try:
return GrampsDBDirAssocCursor(self.reference_map_referenced_map,
self.txn)
@ -696,16 +705,16 @@ class GrampsDBDir(GrampsDbRead, Callback, UpdateCallback):
Returns an interator over a list of (class_name, handle) tuples.
@param handle: handle of the object to search for.
@type handle: database handle
@param include_classes: list of class names to include in the results.
Default: None means include all classes.
@type include_classes: list of class names
:param handle: handle of the object to search for.
:type handle: database handle
:param include_classes: list of class names to include in the results.
Default: None means include all classes.
:type include_classes: list of class names
Note that this is a generator function, it returns a iterator for
use in loops. If you want a list of the results use:
use in loops. If you want a list of the results use::
> result_list = list(find_backlink_handles(handle))
result_list = list(find_backlink_handles(handle))
"""
# Use the secondary index to locate all the reference_map entries
@ -1210,7 +1219,7 @@ class GrampsDBDir(GrampsDbRead, Callback, UpdateCallback):
self.find_next_note_gramps_id if set_gid else None,
self.commit_note)
def do_remove_object(self, handle, transaction, data_map, key):
def __do_remove(self, handle, transaction, data_map, key):
if self.readonly or not handle:
return
@ -1250,7 +1259,7 @@ class GrampsDBDir(GrampsDbRead, Callback, UpdateCallback):
Remove the Source specified by the database handle from the
database, preserving the change in the passed transaction.
"""
self.do_remove_object(handle, transaction, self.source_map,
self.__do_remove(handle, transaction, self.source_map,
SOURCE_KEY)
def remove_event(self, handle, transaction):
@ -1258,7 +1267,7 @@ class GrampsDBDir(GrampsDbRead, Callback, UpdateCallback):
Remove the Event specified by the database handle from the
database, preserving the change in the passed transaction.
"""
self.do_remove_object(handle, transaction, self.event_map,
self.__do_remove(handle, transaction, self.event_map,
EVENT_KEY)
def remove_object(self, handle, transaction):
@ -1266,7 +1275,7 @@ class GrampsDBDir(GrampsDbRead, Callback, UpdateCallback):
Remove the MediaObjectPerson specified by the database handle from the
database, preserving the change in the passed transaction.
"""
self.do_remove_object(handle, transaction, self.media_map,
self.__do_remove(handle, transaction, self.media_map,
MEDIA_KEY)
def remove_place(self, handle, transaction):
@ -1274,7 +1283,7 @@ class GrampsDBDir(GrampsDbRead, Callback, UpdateCallback):
Remove the Place specified by the database handle from the
database, preserving the change in the passed transaction.
"""
self.do_remove_object(handle, transaction, self.place_map,
self.__do_remove(handle, transaction, self.place_map,
PLACE_KEY)
def remove_family(self, handle, transaction):
@ -1282,7 +1291,7 @@ class GrampsDBDir(GrampsDbRead, Callback, UpdateCallback):
Remove the Family specified by the database handle from the
database, preserving the change in the passed transaction.
"""
self.do_remove_object(handle, transaction, self.family_map,
self.__do_remove(handle, transaction, self.family_map,
FAMILY_KEY)
def remove_repository(self, handle, transaction):
@ -1290,7 +1299,7 @@ class GrampsDBDir(GrampsDbRead, Callback, UpdateCallback):
Remove the Repository specified by the database handle from the
database, preserving the change in the passed transaction.
"""
self.do_remove_object(handle, transaction, self.repository_map,
self.__do_remove(handle, transaction, self.repository_map,
REPOSITORY_KEY)
def remove_note(self, handle, transaction):
@ -1298,7 +1307,7 @@ class GrampsDBDir(GrampsDbRead, Callback, UpdateCallback):
Remove the Note specified by the database handle from the
database, preserving the change in the passed transaction.
"""
self.do_remove_object(handle, transaction, self.note_map,
self.__do_remove(handle, transaction, self.note_map,
NOTE_KEY)
def __set_name_group_mapping(self, name, group):
@ -1580,30 +1589,6 @@ class GrampsDBDir(GrampsDbRead, Callback, UpdateCallback):
return newobj
return None
def find_from_handle(self, handle, transaction, class_type, dmap, add_func):
"""
Find a object of class_type in the database from the passed handle.
If no object exists, a new object is added to the database.
@return: Returns a tuple, first the object, second a bool which is True
if the object is new
@rtype: tuple
"""
obj = class_type()
handle = str(handle)
new = True
if handle in dmap:
data = dmap.get(handle, txn=self.txn)
obj.unserialize(data)
#references create object with id None before object is really made
if obj.gramps_id is not None:
new = False
else:
obj.set_handle(handle)
add_func(obj, transaction)
return obj, new
def transaction_begin(self, msg="", batch=False, no_magic=False):
try:
return self.__transaction_begin(msg, batch, no_magic)