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: gramps.gen.utils.callback.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(gen.proxy.LivingProxyDb, 1)
>>> dbstate.apply_proxy(gen.proxy.PrivateProxyDb)

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.

no_database()

Closes the database without a new database

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: exceptions.Exception

Error used to report database errors

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

Bases: exceptions.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: exceptions.Exception

Error used to report BerkeleyDB errors.

TODO

Recent Files

class gramps.gen.recentfiles.RecentFiles

Bases: object

Interface to a RecentFiles collection

add(item2add)

check_if_recent(filename)

do_save()

Saves the current Gramps RecentFiles collection to the associated file.

remove_filename(filename)

rename_filename(filename, new_filename)

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_path()

get_time()

set_name(val)

set_path(val)

set_time(val)

class gramps.gen.recentfiles.RecentParser

Bases: object

Parsing class for the RecentFiles collection.

characters(data)

endElement(tag)

get()

startElement(tag, attrs)

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='')

set_total(total)

update_empty(count=None)

update_real(count=None)

User

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

This class provides a means to interact with the user in an abstract way. This class should be overridden by each respective user interface to provide the appropriate interaction (eg. dialogs for GTK, prompts for CLI).

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

callback(percentage, text=None)

Display the precentage.

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_error(title, error='')

Notify the user of an error.

Parameters:

• title (str) – the title of the error
• error (str) – the error message

Returns:

none

progress(*args, **kwds)

Preferred form of progress reporting.

Parameters: same as for begin_progress.

Usage example (see gramps/cli/test/user_test.py):

with self.user.progress("Foo", "Bar", 0) as step:
    for i in range(10):
        step()

Ensures end_progress will be called even if an exception was thrown.

prompt(title, message, accept_label, reject_label)

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”

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