What is the minimalistic experiment with Simple Access?

Development
1

The Simple Access docs starts with a small example Python.
(Provides a simplified database access interface to the Gramps database.)

sa = SimpleAccess(database)

print "Person        : ", sa.name(person)
print "Gender        : ", sa.gender(person)
print "Birth date    : ", sa.birth_date(person)
print "Birth place   : ", sa.birth_place(person)
print "Death date    : ", sa.death_date(person)
print "Death place   : ", sa.death_place(person)
print "Father        : ", sa.name(sa.father(person))
print "Mother        : ", sa.name(sa.mother(person))
print "Spouse        : ", sa.name(sa.spouse(person))
print "Marriage Type : ", sa.marriage_type(person)
print "Marriage Date : ", sa.marriage_date(person)
print "Marriage Place: ", sa.marriage_place(person)
for child in sa.children(person):
   print "Child         : ", sa.name(child)

# Print out burial and baptism events
for event in sa.events( person , [ "Burial", "Baptism" ]):
   print "Event         : ", sa.event_type(event), sa.event_date(event),
   print sa.event_place(event)

This is supposed to produce:

Person        :  Garner, Lewis Anderson
Gender        :  male
Birth date    :  6/21/1855
Birth place   :  Great Falls, MT
Death date    :  6/28/1911
Death place   :  Twin Falls, ID
Father        :  Garner, Robert W.
Mother        :  Zielinski, Phoebe Emily
Spouse        :  Martel, Luella Jacques
Marriage Type :  Married
Marriage Date :  4/1/1875
Marriage Place:  Paragould, AR
Child         :  Garner, Eugene Stanley
Child         :  Garner, Jesse V.
Child         :  Garner, Raymond E.
Child         :  Garner, Jennie S.
Child         :  Garner, Walter E.
Child         :  Garner, Daniel Webster
Child         :  Garner, Bertha P.
Child         :  Garner, Elizabeth
Event         :  Burial 7/1/1911 Twin Falls, ID
What is most simplistic way this example code can be made to run?

Using the Python Shell gramplet? Maybe a QuickReport add-on?

Note that this was in an older piece of developer documentation. The example code is in Python2 and Gramps has since evolved to use Python3. So the code needs a minor tweak for the newer Print syntax. Also, it helps to insert a line that explicitly shows how that this code can rely upon the database object from the _simpleaccess module in the gramps.gen.simple package:
from gramps.gen.simple._simpleaccess import SimpleAccess

It seems like showing that data for the Active Person is the best “instant gratification” example each addon.

A lesson stepping through with that output is better than a “Hello World” example and could be applied to several add-on types: gramplet, report (with plain text, simple document, simple table implementations), quick report, view mode, tool.

2

Kari has kindly offered a series of SuperTool scripts to demonstrate how to experiment with this specific example.

SuperTool is probably the most workable way to experiment with example snippets of Gramps. without having to construct a lot of extra interface to see any results.

Still, it helps to know where the output will go. And that launching SuperTool from a category makes that object hierarchy available for manipulation.

The examples tend to use the Print command… which sends the output to the Console. So you need to have start Gramps from the command line rather than using the GUI launcher. The output will be routed to that Console window.

In the first experiment, the only changes to the source code are:

  • updating from the Print statement syntax (without parentheses) of Python 2 to the Print function syntax of Python 3.
  • inserting a initialization statement to specify the which package contains the SimpleAccess calls
  • separating the initalization and execution statements.
  1. Click the ‘copy’ button in the upper right corner of the code block below and save the file (your “Documents” is a good location) folder with the name simple-example1_print-to-console.script
  2. Launch Gramps from the command line
  3. load some tree data (Always experiment with the example.gramps tree data, not your main research tree.)
  4. install the SuperTool addon (if necessary)
  5. navigate to the People category and select a person
  6. Tools → Isotammi tools → SuperTool…
  7. from the SuperTool dialog, File → Open
  8. navigate to the folder containing simple-example1_print-to-console.script and load the script
  9. click the Execute button
  10. look at the Console window
[Gramps SuperTool script file]
version=1

[title]
simple-example1_print-to-console

[category]
People

[initial_statements]
from gramps.gen.simple._simpleaccess import SimpleAccess
sa = SimpleAccess(db)

[statements]
print("Person        : ", sa.name(person))
print("Gender        : ", sa.gender(person))
print("Birth date    : ", sa.birth_date(person))
print("Birth place   : ", sa.birth_place(person))
print("Death date    : ", sa.death_date(person))
print("Death place   : ", sa.death_place(person))
print("Father        : ", sa.name(sa.father(person)))
print("Mother        : ", sa.name(sa.mother(person)))
print("Spouse        : ", sa.name(sa.spouse(person)))
print("Marriage Type : ", sa.marriage_type(person))
print("Marriage Date : ", sa.marriage_date(person))
print("Marriage Place: ", sa.marriage_place(person))
for child in sa.children(person):
   print("Child         : ", sa.name(child))

# Print out burial and baptism events
for event in sa.events( person , [ "Burial", "Baptism" ]):
   print("Event         : ", sa.event_type(event), sa.event_date(event), sa.event_place(event))

[filter]

[expressions]

[scope]
selected

[unwind_lists]
False

[commit_changes]
False

[summary_only]
False
If you select multiple people to view this data, you probably ought to add a `print()` line at the beginning and/or end of the statements. The added line separates each person in the output and makes that output more understandable.
3

The next step in the evolution, Kari shows a minimal way to route the output to a table in the SuperTool result Display block instead of the Console. (SuperTool offers the ability to save these results to a CSV file.)

He writes a Print replacement that parses the data, and tabulates it for display. This replacement function is inserted in the Initialization code block and any intance of “print” is replaced in the Statements code block.

image
image702×1032 78.1 KB

Save the following code as simple-example2_print-to-SuperTool.script and load it into SuperTool opened from the People category.


[Gramps SuperTool script file]
version=1

[title]
simple-example2_print-to-SuperTool

[category]
People

[initial_statements]
from gramps.gen.simple._simpleaccess import SimpleAccess
sa = SimpleAccess(db)

def p(title, *values):
   title = title.replace(":","").strip()
   values = list(values)
   while len(values) < 3: values.append("")
   result.add_row([title, *values])

[statements]
p("Person        : ", sa.name(person))
p("Gender        : ", sa.gender(person))
p("Birth date    : ", sa.birth_date(person))
p("Birth place   : ", sa.birth_place(person))
p("Death date    : ", sa.death_date(person))
p("Death place   : ", sa.death_place(person))
p("Father        : ", sa.name(sa.father(person)))
p("Mother        : ", sa.name(sa.mother(person)))
p("Spouse        : ", sa.name(sa.spouse(person)))
p("Marriage Type : ", sa.marriage_type(person))
p("Marriage Date : ", sa.marriage_date(person))
p("Marriage Place: ", sa.marriage_place(person))
for child in sa.children(person):
   p("Child         : ", sa.name(child))

# Print out burial and baptism events
for event in sa.events( person , [ "Burial", "Baptism" ]):
   p("Event         : ", sa.event_type(event), sa.event_date(event), sa.event_place(event))
p("")

[filter]

[expressions]

[scope]
selected

[unwind_lists]
False

[commit_changes]
False

[summary_only]
False
4

Kari created SuperTool partly because the Gramps API was too verbose and limited for his purposes.

This is roughly the equivalent (date formatting is different) done entirely with SuperTool calls:

[Gramps SuperTool script file]
version=1

[title]
simple-example3_SuperTool-Equivalent.script

[category]
People

[initial_statements]
# Using SuperTool syntax 

def p(title, value):
	result.add_row([title, str(value)])

[statements]
p("Person        ", name)
p("Gender        ", gender)
p("Birth date    ", birth.date)
p("Birth place   ", birth.placename)
p("Death date    ", death.date)
p("Death place   ", death.placename)
p("Father        ", father.name)
p("Mother        ", mother.name)
if len(spouses) > 0:
   p("Spouse        ", spouses[0].name)
   p("Marriage Type ", families[0].reltype)
   p("Marriage Date ",  families[0].events[0].date)
   p("Marriage Place", families[0].events[0].placename)
for child in children:
   p("Child         ", child.name)

# Print out burial and baptism events
for event in events:
   if (event.type in [ "Burial", "Baptism" ]):
      p("Event         ", "%s %s %s" % (event.type, event.date, event.placename))

[filter]

[expressions]

[scope]
selected

[unwind_lists]
False

[commit_changes]
False

[summary_only]
False
7

That’s a good point: all of the little demo scripts like this should have a standard snippet that includes how to import and load a database.

Here is a bit of modern code for that example:

from gramps.gen.db.utils import open_database
from gramps.gen.simple import SimpleAccess

database = open_database("Family Tree Name")
sa = SimpleAccess(database)
person = database.get_default_person()

print("Person        : ", sa.name(person))
...
database.close() # important, otherwise is locked

We should work on making gramps easier to do this kind of thing. SuperTool looks amazing, but shouldn’t be needed to have little script-like functionality in any Python-based library IMHO.

3 Likes
8

The Help for SuperTool has been enhanced to be populated from a JSON. Each JSON has a section (which becomes the Tab name) with a 2 column glossary table. Each term optionally has a name, description, hotlink and tooltip.

The first 3 rows in each Primary object has the 3 ways that SuperTool code can reference the filtered set of objects from the active view.

Each category SuperTool handles all the overhead to display and/or change the Properties of an object in that category. I would like help generating a page that gives examples (not pseudo-code) of how to access those Person objects if SuperTool did not exist. As a Quickview, a report, a gramplet, a view and as an external tool.

Then add a 4th row that links to that page. This could enhance SuperTool’s ability to be used as a framework for diving into Gramps developement.

image
image1049×835 76.8 KB