Help on how to develop Gramps

Development
1

Hello!

I know a bit of python, maybe not enough to make big contributions, but I have a few ideas of small things to improve in gramps.
Besides helping in translating Gramps into Spanish, I have made no contributions to Gramps, because I do not know how.
My problem is: I think I know what file to edit in order to make a modification, but I don’t know how to test what I do. For example, I think a variable named ‘name’ might contain the name of a person, but I do not know whether that is true or not, or I don’t know if that variable is a string, a list or any other object.
I am used to work with jupyter notebook. Is there a way to test gramps code in a jupyter notebook or something similar?
It would be great to be able to edit the code with context, for example, use a small database to check what is in the variable ‘name’ for a given person.

Any help is appreciated.

1 Like
2

You probably want to look at the Gramps Data Model diagram. And the Using the database API and Getting started with Gramps development wiki pages. (Note at the bottom of the wiki pages are links to similar categories of pages.

You may find it useful to experiment with the Isotammi Supertool add-on. There ‘help’ is a bare list of field names in each category of objects. You can play with database logic their without dealing with the GUI overhead.

There are some examples of different task being done with different plug-in types: Reports, filter rules, gramplets, quickreports, view modes, tools, import/export modules, etc. Can you also describe (in general) the kind of things that pique your interest?

3

Hello Juan,

Since you work with ubuntu, I think it’s much easier to use the tools that are available on that, and not use Jupyter notebook, because that only complicates things. We have a lot of documentation on our wiki, and you may also try to work with Visual Studio code, which is a free version of Visual Studio that works quite well on Linux.

And to be honest, I think that the wiki can use some improvement, so it helps if you can just start experimenting and document your experiences.

Regards,

Enno

4

I have chosen KDE Plasma desktop manager (instead of Gnome which is the default under Ubuntu). There is a nice and powerful Integrated Development Environment named KDevelop with Python capability. I couple it with an LXR cross-reference browser on the Gramps tree.

But be aware that the source tree is a real can of worms. So, you’d better spend some time studying it carefully. I have also drawn many diagrams to see the relationships between genealogical object classes.

And even so, the code is difficult to manipulate because it is too intricated with two design decisions: GTK+ widgets and DSDDB storage. The code is not structured enough to isolate these choices in independent layers with “agnostic” interfaces. As an example of the consequences, take the present SQLite backstore. Though SQLite is a relational DB, the interface simulates the BSDDB key/value pair concept into SQL. And since BSDDB is limited to a single “value” (column) in a record, the data when “converted” to SQL is a single BLOB (binary large object) containing a Python object, nearly in binary format (well, it is serialised but this does not change the “opacity” of data in the SQLite DB).

5

Does it integrate with git, or can you also recommend a particular git GUI to go with it, or do you just use the command line for that?

6

Yes. And that’s absolutely mandatory to allow you to back up to some stable state if you make a coding error. Also, thanks to git, I can measure my distance or divergence from upstream official version. But for that I prefer to use Git GUI which is better fit for the task.

There are also a bunch of other utilities. For example, to see the impact of my current work on a true SQL DB, I use Sqliteman which I left open so that I can check the effective DB state after each transaction in Gramps.

7

Thanks @pgerlier. May I also ask, which one of these approaches (or something else) you use for isolating your development environment? Is venv a viable option?

Until now I’ve made only minor changes to my local copy of Gramps, but would like to start being more rigorous about it. Having accumulated a number of small patches (mostly from others’ pull requests), I’d like to do a better job of managing things. So any comments from you and others are very helpful. Thanks.

8

Approaches

To better isolate my various activities, I use one account per “theme”: one account for my common “affairs” (e-mail, accounting, web browsing, photos, …), one account for Gramps research (it originated from my choice of KDE Plasma environment and I opened specifically an account for GNOME desktop, but a few upgrades back I dropped Gnome completely as having the libraries installed is enough; so now, even this account is under KDE Plasma), one account for “general” development (Gramps is only the latest one), one account for LXR maintenance (as I am the lead developer), …

Isolation

This is combined with an ad-hoc group policy: the accounts are attached to various groups to allow “easy” file transfers between user home directories. Not all accounts have the same privileges. In particular the “development” accounts are the most limited ones as things may easily go awry.

For backup and exchange purposes I also created a /home/groups/ directory with subdirectories with the same names as the groups. Only the groups have write-access. There is also a /home/groups/projects/ directory where I store “remote” git repos as sync’ed backups for my .git active trees. And a friend of mine offered hosting on his NAS as second-level backup.

Workflow

First I never work on two projects simultaneously. If I must switch to another one under my development account, I close everything, making sure that the state is well defined. I should probably also do a checkpoint with Git but I don’t like to have “pending” commits (meaning the patch sets are not guaranteed to be complete so that applying them will result in a functional app). Perhaps with an adequate commit message telling this is only a temporary backup … Only then I switch to the other project (very easy with KDevelop as it guarantees a clean environment by switching the working directories, setting the correct shell environment, …

My desktop computer is rather well “furbished”. I have 2 wide screens (there are 3 connectors on the GPU card but two out of them are exclusive from each other, so my 3rd monitor was useless). Consequently I can have the KDevelop + Konsole (terminal) windows on one screen, Firefox (code cross-references through LXR), Sqliteman (DB monitoring) and Gramps windows on the other screen.

I mention Konsole because I launch Gramps with a command line. All debugging output (which is normally discarded in GUI mode) is displayed in the Konsole window and I can trace what’s is happening as the Gramps window open and change.

I remember having tried Python venv once on some Django project but I don’t feel at ease with it because I’m discovering Python while modifying Gramps. In addition what you change in venv is not forwarding to your code files. I find it as quick to leave Gramps and to patch the source file then relaunch Gramps as playing in venv.

Git

Git is your friend. I cloned the official Gramps repo (not the one where PR are pushed because I don’t want to subscribe to one more site, be it GitHub).

The first thing to do is to create your own branch. This isolates you from the development on the master branch. You then control when you want to rebase to see if your changes are compatible with mainstream.

I use Git frequently to compare my state with master (or any other branch) to see if I am relatively close to official releases. My goal is to avoid to diverge too much so that I can still benefit from progress on the main branch.

Git also allows me to eventually revert a dead end or cancel the effects of a badly designed patch.

Other tools

Kompare: KDE Plasma GUI front-end to diff.

LXR: interactive browsing on source code; you can have several tabs in Firefox to show you several files; identifiers are clickable to display the list of definitions and uses; you can click on these to jump to the line in the file (comes in complement to what KDevelop offers).

LibreOffice Draw & Writer: to make diagrams on Gramps internals and take structured notes on my discoveries in the source code as well as my introspection on what I’d like

9

@jcsaaver The replies so far give good information about the data model, IDEs and environments which should help. It would be cool to set up a REPL environment to test out Gramps code quickly, but I don’t know if there is. I’ll suggest something else which may not be exactly what you’re looking for, but it will help test and validate any code you create: writing unit tests.

Writing unit tests for testing your assumptions and code will build confidence and eventually these tests would prove the correctness of new code you write. By adding it to the Gramps repo, it will be a permanent test against regression. Look through existing unit tests found in test folders in the repo for examples.

10

You can use the Python Evaluation gramplet for this purpose. Add it to the Dashboard view and then use it as a detached window.

The database is accessible through the self.dbstate.db variable. As an example you could print the name of the default person with the following code:

from gramps.gen.display.name import displayer as nd

person = self.dbstate.db.get_default_person()
print (nd.display(person))

To find the type of a variable use:

print type(person)

You will need to use the database API to retrieve objects and use object library to find the information you require.

In addition there is utility code to make things easier. For example, you will probably want to use the name, date and place displayers rather than formatting the data yourself.

If you want to write GUI code, then knowledge of Gtk3 is also required.

11

Wow! Had no idea about the Python Shell addon, that’s really cool.

Just tried out the code you shared, and one thing that threw me off is that the output of the print() command goes the console window of Gramps AIO on Windows rather than the Python Shell, although the output of other commands like dir() show in the Python Shell itself. Not sure what the difference is, but until I figured that out, I thought the shell wasn’t working.

Anyway, thanks for exposing this addon. This might be what the OP @jcsaaver was looking for too.

12

Thanks to all for your replies!
I have not had much time, so I have not been able to test what you have said, but at least I will have somewhere to start from

13

This topic was automatically closed 30 days after the last reply. New replies are no longer allowed.