Difference between revisions of "Addon:Generic DB Access lib"

From Gramps
Jump to: navigation, search
m (See also: fix broken link)
 
(10 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
{{Third-party plugin}}
 
{{Third-party plugin}}
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 ).
+
{{man warn|Experimental library|Please only use on a copy of your Family Tree}}
{{stub}}
+
[[File:Libaccess.jpg|right|thumb]]
 +
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 ==
 
== Usage ==
  
 
=== Example ===
 
=== 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==
 
==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.
 
* [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
 
* 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.
 
* [[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:Plugins]]
 
[[Category:Developers/General]]
 
[[Category:Developers/General]]
 
[[Category:Reports]]
 
[[Category:Reports]]

Latest revision as of 21:39, 22 February 2022

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.

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