The gramps.gen Module

The gen module provides packages that are common to all gramps interfaces (gui, cli and web).

Database State

Provide the database state class

class gramps.gen.dbstate.DbState

Bases: Callback

Provide a class to encapsulate the state of the database.

apply_proxy(proxy, *args, **kwargs)

Add a proxy to the current database. Use pop_proxy() to revert to previous db.

>>> dbstate.apply_proxy(gramps.gen.proxy.LivingProxyDb, 0)
>>> dbstate.apply_proxy(gramps.gen.proxy.PrivateProxyDb)

>>> from gramps.gen.filters.rules.person import (IsDescendantOf,
                                                 IsAncestorOf)
>>> from gramps.gen.filters import GenericFilter
>>> filter = GenericFilter()
>>> filter.set_logical_op("or")
>>> filter.add_rule(IsDescendantOf([db.get_default_person().gramps_id,
                                    True]))
>>> filter.add_rule(IsAncestorOf([db.get_default_person().gramps_id,
                                  True]))
>>> dbstate.apply_proxy(gramps.gen.proxy.FilterProxyDb, filter)

change_database(database)

Closes the existing db, and opens a new one. Retained for backward compatibility.

change_database_noclose(database)

Change the current database. and resets the configuration prefixes.

get_database()

Get a reference to the current database.

is_open()

Returns True if DbState.db refers to a database object instance, AND the database is open.

This tests both for the existence of the database and its being open, so that for the time being, the use of the dummy database on closure can continue, but at some future time, this could be altered to just set the database to none.

This replaces tests on DbState.open, DbState.db, DbState.db.is_open() and DbState.db.db_is_open all of which are deprecated.

no_database()

Closes the database without a new database (except for the DummyDb)

pop_proxy()

Remove the previously applied proxy.

>>> dbstate.apply_proxy(gen.proxy.LivingProxyDb, 1)
>>> dbstate.pop_proxy()
>>> dbstate.apply_proxy(gen.proxy.PrivateProxyDb)
>>> dbstate.pop_proxy()

signal_change()

Emits the database-changed signal with the new database

Errors

Provide Error objects

class gramps.gen.errors.DatabaseError(value='')

Bases: Exception

Error used to report database errors

class gramps.gen.errors.DateError(value='')

Bases: Exception

Error used to report Date errors

Might have a .date attribute holding an invalid Date object that triggered the error.

class gramps.gen.errors.DbError(value)

Bases: Exception

Error used to report BerkeleyDB errors.

TODO

Recent Files

class gramps.gen.recentfiles.RecentFiles

Bases: object

Interface to a RecentFiles collection

add(item2add)

Add a file to the recent files list.

check_if_recent(filename)

Check if a file is present in the recent files list.

do_save(fname)

Saves the current Gramps RecentFiles collection to the associated file.

remove_filename(filename)

Remove a file from the recent files list.

rename_filename(filename, new_filename)

Rename a file in the recent files list.

save()

Attempt saving into XML. The trick is not to fail under any circumstances.

class gramps.gen.recentfiles.RecentItem(p='', n='', t=0)

Bases: object

Interface to a single Gramps recent-items item

get_name()

Get the file name.

get_path()

Get the file path.

get_time()

Get the file timestamp.

set_name(val)

Set the file name.

set_path(val)

Set the file path.

set_time(val)

Set the file timestamp.

class gramps.gen.recentfiles.RecentParser

Bases: object

Parsing class for the RecentFiles collection.

characters(data)

Handler for XML character data.

end_element(tag)

Handler for XML end element.

get()

Return a list of recent files.

start_element(tag, attrs)

Handler for XML start element.

Sort

Provide sorting routines for use in Gramps. Since these functions are intended to provide fast sorting, they tend to bypass access methods, and directly use class members. For this reason, care needs to be taken to make sure these remain in sync with the rest of the design.

class gramps.gen.sort.Sort(database)

Bases: object

by_birthdate_key(first_id)

Sort routine for comparing two people by birth dates. If the birth dates are equal, sorts by name

by_date_key(a_id)

Sort routine for comparing two events by their dates.

by_event_description_key(a_id)

Sort routine for comparing two events by their descriptions.

by_event_id_key(a_id)

Sort routine for comparing two events by their ID.

by_event_place_key(a_id)

Sort routine for comparing two events by their places.

by_event_type_key(a_id)

Sort routine for comparing two events by their type.

by_last_name_key(first_id)

Sort routine for comparing two last names. If last names are equal, uses the given name and suffix

by_media_title_key(a_id)

Sort routine for comparing two media objects by their title.

by_place_title_key(a_id)

Sort routine for comparing two places.

by_sorted_name_key(first_id)

Sort routine for comparing two displayed names.

Update callback

A set of basic utilities that everything in Gramps can depend upon.

The goal is to have this module not depend on any other gramps module. That way, e.g. database classes can safely depend on that without other Gramps baggage.

class gramps.gen.updatecallback.UpdateCallback(callback, interval=1)

Bases: object

Basic class providing way of calling the callback to update things during lengthy operations.

reset(text='')

Reset the count to zero.

set_text(text)

Set the text.

set_total(total)

Set the total.

update_empty(count=None)

Dummy update used when no callback is specified.

update_real(count=None)

Called when the count is updated.

User

The User class provides basic interaction with the user.

class gramps.gen.user.User(callback=None, error=None, uistate=None, dbstate=None)

Bases: UserBase

An implementation of the gen.user.UserBase class which supresses output and accepts prompts. This is useful for unit tests.

begin_progress(title, message, steps)

Start showing a progress indicator to the user.

Don’t use this method directly, use progress instead.

Parameters:

• title (str) – the title of the progress meter

• message (str) – the message associated with the progress meter

• steps (int) – the total number of steps for the progress meter. a value of 0 indicates that the ending is unknown and the meter should just show activity.

Returns:

none

end_progress()

Stop showing the progress indicator to the user.

Don’t use this method directly, use progress instead.

info(msg1, infotext, parent=None, monospaced=False)

Displays information to the user

notify_db_error(error)

Notify the user of a DB error.

Parameters:

error (str) – the error message

Returns:

none

notify_db_repair(error)

Notify the user their DB might need repair.

Parameters:

error (str) – the error message

Returns:

none

notify_error(title, error='')

Notify the user of an error.

Parameters:

• title (str) – the title of the error

• error (str) – the error message

Returns:

none

prompt(title, message, accept_label, reject_label, parent=None, default_label=None)

Prompt the user with a message to select an alternative.

Parameters:

• title (str) – the title of the question, e.g.: “Undo history warning”

• message – the message, e.g.: “Proceeding with the tool will erase the undo history. If you think you may want to revert running this tool, please stop here and make a backup of the DB.”

• accept_label (str) – what to call the positive choice, e.g.: “Proceed”

• reject_label (str) – what to call the negative choice, e.g.: “Stop”

• default_label (str or None) – the label of the default

Returns:

the user’s answer to the question

Return type:

bool

step_progress()

Advance the progress meter.

Don’t use this method directly, use progress instead.

warn(title, warning='')

Warn the user.

Parameters:

• title (str) – the title of the warning

• warning (str) – the warning

Returns:

none