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 *

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

@ -94,52 +94,14 @@ class GrampsDbBase(object):
"""
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
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
"""
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
@ -948,12 +879,6 @@ class GrampsDbBase(object):
"""
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
@ -963,12 +888,6 @@ class GrampsDbBase(object):
"""
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
@ -978,38 +897,6 @@ class GrampsDbBase(object):
"""
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):
"""
Return a list of database handles, one handle for each Repository in
@ -1017,12 +904,6 @@ class GrampsDbBase(object):
"""
raise NotImplementedError
def iter_repository_handles(self):
"""
Return an iterator over handles for Repositories in the database
"""
raise NotImplementedError
def get_note_handles(self):
"""
Return a list of database handles, one handle for each Note in the
@ -1030,12 +911,102 @@ class GrampsDbBase(object):
"""
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):
"""
Return an iterator over handles for Notes in the database
"""
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.
@ -1700,11 +1677,11 @@ class GrampsDbBase(object):
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
@ -1712,10 +1689,11 @@ class GrampsDbBase(object):
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(find_backlink_handles(handle))
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)