Difference between revisions of "Simple Access API"

From Gramps
Jump to: navigation, search
(fixed link format, and pointed directly to file)
m (Gramps)
(10 intermediate revisions by 5 users not shown)
Line 1: Line 1:
As of version 3.0, a database API directed to plugin writers is available, The Simple Access API, accompanied with a Simple Document API for easy presentation of the data.
+
As of Gramps version 3.0, a database API directed to plugin writers is available, The Simple Access API, accompanied with a Simple Document API for easy presentation of the data.
  
[[Category:Developers/General]][[Category:Developers/Tutorials]]
+
==Introduction==
  
==Introduction==
+
The normal database routines are optimized for low memory usage, and if used properly, will take up almost no memory. This is key when using large databases. Typically, instead of maintaining dictionaries or lists of objects, we can use the database "handles", and access the data only when explicitly needed. This memory efficiency comes at the cost of being fairly complicated to use.
The normal database routines are optimized for low memory usage, and if
 
used properly, will take up almost no memory. This is key when using
 
large databases. Typically, instead of maintaining dictionaries or lists
 
of objects, we can use the database "handles", and access the data only
 
when explicitly needed. This memory efficiency comes at the cost of
 
being fairly complicated to use.
 
  
The simplified API hides most of the complexity. Full objects are
+
The simplified API hides most of the complexity. Full objects are returned, so you can easily consume a lot of memory with large databases. The routines themselves do not consume a significant amount of memory, but if you decided to keep your own lists or dictionaries of data, you will consume memory quickly.  
returned, so you can easily consume a lot of memory with large
 
databases. The routines themselves do not consume a significant amount
 
of memory, but if you decided to keep your own lists or dictionaries of
 
data, you will consume memory quickly.  
 
  
This class is specifically constructed for use in the plugins, or to make [[Quick Reports|quick reports]] (available in the context menu's).  
+
This class is specifically constructed for use in the plugins, or to make [[Quick Views|quick views]] (available in the context menu's).
  
 
==What is available?==
 
==What is available?==
You can view the API in '''_SimpleAccess.py''' right [http://gramps.svn.sourceforge.net/viewvc/gramps/trunk/src/Simple/_SimpleAccess.py?view=markup here].  
+
 
 +
You can view the API in [http://svn.code.sf.net/p/gramps/code/trunk/gramps/gen/simple/_simpleaccess.py _simpleaccess.py].  
  
 
Example use:
 
Example use:
  from Simple import SimpleAccess
+
  from simple import simpleaccess
  sdb = SimpleAccess(database)
+
  sdb = simpleaccess(database)
 
  # grab our current id, so we can filter the active person out
 
  # grab our current id, so we can filter the active person out
 
  # of the data
 
  # of the data
Line 35: Line 26:
 
       #print something to terminal
 
       #print something to terminal
 
       print sdb.name(child),sdb.gender(child), sdb.birth_date(child))
 
       print sdb.name(child),sdb.gender(child), sdb.birth_date(child))
 +
 +
[[Category:Developers/General]]
 +
[[Category:Developers/Tutorials]]
 +
[[Category:Reports|A]]
 +
[[Category:Views|A]]

Revision as of 03:35, 1 February 2013

As of Gramps version 3.0, a database API directed to plugin writers is available, The Simple Access API, accompanied with a Simple Document API for easy presentation of the data.

Introduction

The normal database routines are optimized for low memory usage, and if used properly, will take up almost no memory. This is key when using large databases. Typically, instead of maintaining dictionaries or lists of objects, we can use the database "handles", and access the data only when explicitly needed. This memory efficiency comes at the cost of being fairly complicated to use.

The simplified API hides most of the complexity. Full objects are returned, so you can easily consume a lot of memory with large databases. The routines themselves do not consume a significant amount of memory, but if you decided to keep your own lists or dictionaries of data, you will consume memory quickly.

This class is specifically constructed for use in the plugins, or to make quick views (available in the context menu's).

What is available?

You can view the API in _simpleaccess.py.

Example use:

from simple import simpleaccess
sdb = simpleaccess(database)
# grab our current id, so we can filter the active person out
# of the data
person = database.active_person()
gid = sdb.gid(database.active_person())
# loop through each family in which the person is a child
for family in sdb.child_in(person):
  # loop through each child in the family
  for child in sdb.children(family):
     #print something to terminal
     print sdb.name(child),sdb.gender(child), sdb.birth_date(child))