Addon:Generic DB Access lib

From Gramps
Jump to: navigation, search
Gramps-notes.png

Please use carefully on data that is backed up, and help make it better by reporting any comments or problems to the author, or issues to the bug tracker
Unless otherwise stated on this page, you can download this addon by following these instructions.
Please note that some Addons have prerequisites that need to be installed before they can be used.
This Addon/Plugin system is controlled by the Plugin Manager.
An Addons Offline Manual is available for review.

Gnome-important.png
Experimental library

Please only use on a copy of your Family Tree

Libaccess.jpg

The Generic DB Access lib (AKA libaccess) is an experimental library that provides generic access to the database and the gen.lib interface(AKA The core library of Gramps objects ). It was designed to simplify the manner in which developers interact with Gramps.

Usage

Example

Consider the problem of finding out how many people were born in March. Basically, we need to go through the database, get the reference (if one) to the birth event, look up the birth event, if found, get the date from it, get the month and compare it. That might look like this:

count = 0
for p in db.iter_people():
    birth_ref = p.get_birth_ref()
    if birth_ref:
        event = db.get_event_from_handle(birth_ref.ref)
        if event:
            date = event.get_date_object()
            if date.get_month() == 3:
                count += 1

This example is not unusual; you’d have to do something like this whatever it is that you are doing. And this is a simple example. It can get much more complicated. But even in this “simple” example, you have to know a lot about the gen.lib objects that make up Gramps (things like Person, Event, and Date) but you also need to know the interface to the database (things like iter_people, get_event_from_handle) and how things are linked together (handles and refs).

Here is how you would solve the above using this experimental Gramps addon:

from libaccess import *
init(dbstate.db)
len([p for p in Person.all() if p.birth.date.month == 3])

That’s it. Now there’s quite a bit going on here, but I think the most interesting is that this works even if a person doesn’t have a birth event, or if the birth event happens to be missing (eg, the database is in an inconsistent state). By allowing this, it makes chained accessors (item.item.item) possible to use to get to the endpoint to make the comparison (month == 3). Also, one doesn’t need to know anything about the database or gen.lib objects other than the field names we’re interested in.

See also