View source for Addon:Generic DB Access lib

{{Third-party addon}}
{{man warn|Experimental library|Please only use on a copy of your Family Tree}}
The {{man label|Generic DB Access lib}} (AKA libaccess) is an experimental library that provides generic access to the database and the [https://gramps-project.org/docs/gen/gen_lib.html#module-gramps.gen.lib 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:

<pre>
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
</pre>

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:

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

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==
* [https://gramps-project.org/blog/2010/01/alternative-interfaces/ Alternative Interfaces], Date: January 23rd, 2010, by Doug Blank, who introduced {{man label|libaccess}} in Gramps 3.2.
* Source code for Gramps master: https://github.com/gramps-project/addons-source/tree/master/libaccess
* [https://sourceforge.net/p/gramps/mailman/message/30213240/ GEPS : single-line sql-like filter field (libaccess based ?)], Dec 11, 2012, ''...I don't plan on developing that particular prototype[libaccess] any further,...''' Doug Blank
* [[GEPS 017: Flexible gen.lib Interface]] - Proposal was withdrawn as after building a prototype, it was found to be too slow for general use.
* [[Addon:Isotammi_addons#SuperTool]] - general purpose scripting tool that can be used to do "ad-hoc" queries against a Gramps family tree/database.


[[Category:Plugins]]
[[Category:Developers/General]]
[[Category:Reports]]