The gramps.gen.plug Module

The “plug” package for handling plugins in Gramps.

Plugin

This module provides the base class for plugins.

class gramps.gen.plug._plugin.Plugin(name, description, module_name)

Bases: object

This class serves as a base class for all plugins that can be registered with the plugin manager

get_description()

Get the description of this plugin.

Returns:a string that describes the plugin

get_module_name()

Get the name of the module that this plugin lives in.

Returns:a string representing the name of the module for this plugin

get_name()

Get the name of this plugin.

Returns:a string representing the name of the plugin

BaseManager

The core of the Gramps plugin system. This module provides capability to load plugins from specified directories and provide information about the loaded plugins.

Plugins are divided into several categories. These are: reports, tools, importers, exporters, quick reports, and document generators.

class gramps.gen.plug._manager.BasePluginManager

Bases: object

unique singleton storage class for a PluginManager.

empty_managed_plugins()

For some plugins, managed Plugin are used. These are only reobtained from the registry if this method is called

get_docgen_names()

Get the list of docgen plugin names.

Returns:a list of DocGenPlugin names

get_docgen_plugins()

Get the list of docgen plugins.

Returns:DocGenPlugin (a list of DocGenPlugin instances)

get_export_plugins()

Get the list of export plugins.

Returns:ExportPlugin (a list of ExportPlugin instances)

get_external_opt_dict()

Return the dictionary of external options.

get_fail_list()

Return the list of failed plugins.

get_import_plugins()

Get the list of import plugins.

Returns:ImportPlugin (a list of ImportPlugin instances)

static get_instance()

Use this function to get the instance of the PluginManager

get_module_description(module)

Given a module name, return the module description.

get_plugin(id)

Returns a plugin object from PluginRegister by id.

get_plugin_data(category)

Gets all of the data from general plugins of type category. plugin.data may be a single item, an iterable, or a callable.

>>> PLUGMAN.get_plugin_data('CSS')
<a list of raw data items>

get_reg_bookitems()

Return list of reports registered as bookitem

get_reg_docgens()

Return list of registered docgen

get_reg_exporters()

Return list of registered exporters

get_reg_general(category=None)

Return list of registered general libs

get_reg_gramplets()

Return list of non hidden gramplets.

get_reg_importers()

Return list of registered importers

get_reg_mapservices()

Return list of registered mapservices

get_reg_quick_reports()

Return list of registered quick reports

get_reg_reports(gui=True)

Return list of registered reports :param gui: bool indicating if GUI reports or CLI reports must be returned

get_reg_sidebars()

Return list of registered sidebars.

get_reg_tools(gui=True)

Return list of registered tools :aram gui: bool indicating if GUI reports or CLI reports must be returned

get_reg_views()

Return list of registered views

get_success_list()

Return the list of succeeded plugins.

import_plugin(pdata)

Rather than just __import__(id), this will add the pdata.fpath to sys.path first (if needed), import, and then reset path.

is_loaded(pdata_id)

return True if plugin is already loaded

load_plugin(pdata)

Load a PluginData object. This means import of the python module. Plugin directories are added to sys path, so files are found

load_plugin_category(category)

Make sure all plugins of a type are loaded.

process_plugin_data(category)

Gathers all of the data from general plugins of type category, and pass it to a single process function from one of those plugins.

>>> PLUGMAN.process_plugin_data('CSS')
<a list of processed data items>

reg_plugins(direct, dbstate=None, uistate=None, load_on_reg=False)

Searches the specified directory, and registers python plugin that are being defined in gpr.py files.

If a relationship calculator for env var LANG is present, it is immediately loaded so it is available for all.

register_option(option, guioption)

Register an external option.

Register a mapping from option to guioption for an option that is not native to Gramps but provided by the plugin writer. This should typically be called during initialisation of a ReportOptions class.

Parameters:

• option (class that inherits from gen.plug.menu.Option) – the option class
• guioption (class that inherits from Gtk.Widget.) – the gui-option class

reload(module, pdata)

Reloads modules that might not be in the path.

reload_plugins()

Reload previously loaded plugins

Export

This module provides the Plugin class for export plugins.

class gramps.gen.plug._export.ExportPlugin(name, description, export_function, extension, config=None)

Bases: gramps.gen.plug._plugin.Plugin

This class represents a plugin for exporting data from Gramps

get_config()

Get the config.

Returns:(??,??)

get_export_function()

Get the export function for this plugin.

Returns:the callable export_function passed into __init__()

get_extension()

Get the file extension for the export file.

Returns:str

Gramplet

class gramps.gen.plug._gramplet.Gramplet(gui, nav_group=0)

Bases: object

Base class for non-graphical gramplet code.

active_changed(handle)

Developers should put their code that occurs when the active person is changed.

add_option(option)

Add an option to the GUI gramplet.

append_text(text, scroll_to='end')

Append the text to the textview. Additionally, move the cursor to the position given. Positions are:

Position	Description
‘start’	start of textview
‘end’	end of textview
‘begin’	begin of line, before setting the text.

build_options()

External constructor for developers to put code for building options.

clear_text()

Clear all of the text from the textview.

connect(signal_obj, signal, method)

connect_signal(nav_type, method)

Connect the given method to the active-changed signal for the navigation type requested.

db_changed()

Method executed when the database is changed.

disconnect(signal)

get_active(nav_type)

Return the handle of the active object for the given navigation type.

get_active_object(nav_type)

Return the object of the active handle for the given navigation type. Assumes nav_type is one of the codes of Db.get_by_name.

get_option(label)

Retireve an option by its label text.

get_option_widget(label)

Retrieve an option’s widget by its label text.

get_text()

Returns the current text of the textview.

hidden_widgets()

A list of widgets to keep hidden. Needed because Gramps uses show_all() in some places.

init()

External constructor for developers to put their initialization code. Designed to be overridden.

insert_text(text)

Insert the given text in the textview at the cursor.

interrupt(*args)

Force the generator to stop running.

link(text, link_type, data, size=None, tooltip=None)

Creates a clickable link in the textview area.

load_data_to_text(pos=0)

Load information from the data portion of the saved Gramplet to the textview.

main()

The main place for the gramplet’s code. This is a generator. Generator which will be run in the background, through update().

no_wrap()

The view in gramplet should not wrap. DEPRICATED: use set_wrap() instead.

on_load()

Gramplets should override this to take care of loading previously their special data.

on_save()

Gramplets should override this to take care of saving their special data.

pause(*args)

Pause the main() method.

post_init()

render_text(text)

Render the given text, given that set_use_markup() is on.

resume(*args)

Resume the main() method that has previously paused.

save_options()

save_text_to_data()

Save the textview to the data portion of a saved gramplet.

save_update_options(obj)

Save a gramplet’s options to file.

set_active(nav_type, handle)

Change the handle of the active object for the given navigation type.

set_has_data(value)

Set the status as to whether this gramplet has data.

set_text(text, scroll_to='start')

Clear and set the text to the given text. Additionally, move the cursor to the position given. Positions are:

Position	Description
‘start’	start of textview
‘end’	end of textview
‘begin’	begin of line, before setting the text.

set_tooltip(tip)

Sets the tooltip for this gramplet.

set_use_markup(value)

Allows the use of render_text to show markup.

set_wrap(value)

Set the textview to wrap or not.

update(*args)

The main interface for running the main() method.

update_all(*args)

Force the main loop to run right now (as opposed to running in background).

update_has_data()

By default, assume that the gramplet has data.

Import

This module provides the Plugin class for import plugins.

class gramps.gen.plug._import.ImportPlugin(name, description, import_function, extension)

Bases: gramps.gen.plug._plugin.Plugin

This class represents a plugin for importing data into Gramps

get_extension()

Get the extension for the files imported by this plugin.

Returns:str

get_import_function()

Get the import function for this plugins.

Returns:the callable import_function passed into __init__()

Menu

Abstracted option handling.

class gramps.gen.plug.menu._menu.Menu

Bases: object

Introduction

A Menu is used to maintain a collection of options that need to be represented to the user in a non-implementation specific way. The options can be described using the various option classes. A menu contains many options and associates them with a unique name and category.

Usage

Menus are used in the following way.

1. Create an option object and configure all the attributes of the option.
2. Add the option to the menu by specifying the option, name and category.
3. Add as many options as necessary.
4. When all the options are added, the menu can be stored and passed to the part of the system that will actually represent the menu to the user.

add_option(category, name, option)

Add an option to the menu.

Parameters:

• category (string) – A label that describes the category that the option belongs to. Example: “Report Options”
• name (string) – A name that is unique to this option. Example: “generations”
• option (gen.plug.menu.Option) – The option instance to be added to this menu.

Returns:

nothing

get_all_option_names()

Get a list of all the option names in this menu.

Returns:a list of strings

get_categories()

Get a list of categories in this menu.

Returns:a list of strings

get_option(category, name)

Get an option with the specified category and name.

Returns:an Option instance or None on failure.

get_option_by_name(name)

Get an option with the specified name.

Returns:an Option instance or None on failure.

get_option_names(category)

Get a list of option names for the specified category.

Returns:a list of strings

Option class representing a boolean (yes/no, true/false).

class gramps.gen.plug.menu._boolean.BooleanOption(label, value)

Bases: gramps.gen.plug.menu._option.Option

This class describes an option that is a boolean (True or False).

Option class representing a list of boolean values.

class gramps.gen.plug.menu._booleanlist.BooleanListOption(heading)

Bases: gramps.gen.plug.menu._option.Option

This class describes an option that provides a list of check buttons.

add_button(description, default)

Add a check button to the list.

Parameters:

• description (string) – A description for this check button. Example: “Census”
• value (int) – The default for this check button (True or False). Example: True

Returns:

nothing

get_descriptions()

Get a list of check button descriptions for this option.

Returns:a list of check button descriptions.

get_selected()

Get a list of descriptions where the check button is selected.

Returns:a list of check button descriptions.

Option class representing a color.

class gramps.gen.plug.menu._color.ColorOption(label, value)

Bases: gramps.gen.plug.menu._option.Option

This class describes an option that allows the selection of a color.

Option class representing a file destination.

class gramps.gen.plug.menu._destination.DestinationOption(label, value)

Bases: gramps.gen.plug.menu._string.StringOption

This class describes an option that specifies a destination file or path. The destination can be a directory or a file. If the destination is a file, the extension can be specified.

get_directory_entry()

Returns:True if the destination is a directory. False if the destination is a file. Return type:bool

get_extension()

Returns:The extension for the destination file.

set_directory_entry(is_directory)

Parameters:is_directory (bool) – Specifies whether the destination is a directory or a file. Returns:nothing

set_extension(extension)

Parameters:extension (str) – Specifies the extension for the destination file. Returns:nothing

Option class representing an enumerated list of possible values.

class gramps.gen.plug.menu._enumeratedlist.EnumeratedListOption(label, value)

Bases: gramps.gen.plug.menu._option.Option

This class describes an option that provides a finite number of values. Each possible value is assigned a value and a description.

add_item(value, description)

Add an item to the list of possible values.

Parameters:

• value (int) – The value that corresponds to this item. Example: 5
• description (string) – A description of this value. Example: “8.5 x 11”

Returns:

nothing

clear()

Clear all possible values from this option.

Returns:nothing.

get_items()

Get all the possible values for this option.

Returns:an array of tuples containing (value,description) pairs.

set_items(items)

Add a list of items to the list of possible values.

Parameters:items (array) – A list of tuples containing value, description pairs. Example: [ (5,”8.5 x 11”), (6,”11 x 17”)] Returns:nothing

set_value(value)

Set the value of this option.

Parameters:value (The type will depend on the type of option.) – A value for this option. Example: True Returns:nothing

Option class representing a family.

class gramps.gen.plug.menu._family.FamilyOption(label)

Bases: gramps.gen.plug.menu._string.StringOption

This class describes an option that allows a family from the database to be selected.

Option class representing a list of filters.

class gramps.gen.plug.menu._filter.FilterOption(label, value)

Bases: gramps.gen.plug.menu._enumeratedlist.EnumeratedListOption

This class describes an option that provides a list of person filters. Each possible value represents one of the possible filters.

get_filter()

Return the currently selected filter object.

Returns:A filter object.

set_filters(filter_list)

Set the list of filters available to be chosen from.

Parameters:filter_list (array) – An array of person filters. Returns:nothing

Option class representing a media object.

class gramps.gen.plug.menu._media.MediaOption(label)

Bases: gramps.gen.plug.menu._string.StringOption

This class describes an option that allows a media object from the database to be selected.

Option class representing a string.

class gramps.gen.plug.menu._note.NoteOption(label)

Bases: gramps.gen.plug.menu._string.StringOption

This class describes an option that allows a note from the database to be selected.

Option class representing a number.

class gramps.gen.plug.menu._number.NumberOption(label, value, min_val, max_val, step=1)

Bases: gramps.gen.plug.menu._option.Option

This class describes an option that is a simple number with defined maximum and minimum values.

get_max()

Get the maximum value for this option.

Returns:an int that represents the maximum value for this option.

get_min()

Get the minimum value for this option.

Returns:an int that represents the minimum value for this option.

get_step()

Get the step size for this option.

Returns:an int that represents the step size for this option.

The base option class for all other option classes.

class gramps.gen.plug.menu._option.Option(label, value)

Bases: gramps.gen.utils.callback.Callback

This class serves as a base class for all options. All Options must minimally provide the services provided by this class. Options are allowed to add additional functionality.

get_available()

Get the availability of this option.

Returns:A Bool indicating the availablity of this option. True indicates that the option is available. False indicates that the option is not available.

get_help()

Get the help information for this option.

Returns:A string that provides additional help beyond the label.

get_label()

Get the friendly label for this option.

Returns:string

get_value()

Get the value of this option.

Returns:The option value.

set_available(avail)

Set the availability of this option.

Parameters:avail (Bool) – An indicator of whether this option is currently available. True indicates that the option is available. False indicates that the option is not available. Returns:nothing

set_help(help_text)

Set the help information for this option.

Parameters:help – A string that provides additional help beyond the label. Example: “Whether to include or exclude people who are calculated to be alive at the time of the generation of this report” Returns:nothing

set_label(label)

Set the friendly label for this option.

Parameters:label (string) – A friendly label to be applied to this option. Example: “Exclude living people” Returns:nothing

set_value(value)

Set the value of this option.

Parameters:value (The type will depend on the type of option.) – A value for this option. Example: True Returns:nothing

Option class representing a person.

class gramps.gen.plug.menu._person.PersonOption(label)

Bases: gramps.gen.plug.menu._string.StringOption

This class describes an option that allows a person from the database to be selected.

Option class representing a list of people.

class gramps.gen.plug.menu._personlist.PersonListOption(label)

Bases: gramps.gen.plug.menu._option.Option

This class describes a widget that allows multiple people from the database to be selected.

Option class representing a list of places.

class gramps.gen.plug.menu._placelist.PlaceListOption(label)

Bases: gramps.gen.plug.menu._option.Option

This class describes a widget that allows multiple places from the database to be selected.

Option class representing a string.

class gramps.gen.plug.menu._string.StringOption(label, value)

Bases: gramps.gen.plug.menu._option.Option

This class describes an option that is a simple one-line string.

Option class representing a document style.

class gramps.gen.plug.menu._style.StyleOption(label, default_style, module_name)

Bases: gramps.gen.plug.menu._enumeratedlist.EnumeratedListOption

This class describes an option that allows the use to select a style sheet.

get_default_style()

Get the default style

get_style()

Get the selected style

get_style_file()

Get the name of the style file

Option class representing color/surname mappings.

class gramps.gen.plug.menu._surnamecolor.SurnameColorOption(label)

Bases: gramps.gen.plug.menu._option.Option

This class describes a widget that allows multiple surnames to be selected from the database, and to assign a color (not necessarily unique) to each one.

Option class representing a block of text.

class gramps.gen.plug.menu._text.TextOption(label, value)

Bases: gramps.gen.plug.menu._option.Option

This class describes an option that is a multi-line string.

Options

General option handling, including saving and parsing.

class gramps.gen.plug._options.MenuOptions

Bases: object

Introduction

A MenuOptions is used to implement the necessary functions for adding options to a menu.

add_menu_option(category, name, option)

Add a single option to the menu.

add_menu_options(menu)

Add the user defined options to the menu.

Parameters:menu (Menu) – A menu class for the options to belong to. Returns:nothing

add_user_options()

Generic method to add user options to the menu.

make_default_style(default_style)

This function is currently required by some reports.

parse_user_options()

Load the changed values into the saved options.

class gramps.gen.plug._options.OptionHandler(module_name, options_dict, person_id=None)

Bases: object

Implements handling of the options for the plugins.

get_person_id()

init_common()

init_subclass()

save_common_options()

save_options()

Saves options to file.

We need to only store non-default options. Therefore, we remove all options whose values are the defaults prior to saving.

set_common_options()

set_options()

Set options to be used in this plugin according to the passed options dictionary.

Dictionary values are all strings, since they were read from XML. Here we need to convert them to the needed types. We use default values to determine the type.

set_person_id(val)

class gramps.gen.plug._options.OptionList

Bases: object

Implements a set of options to parse and store for a given module.

get_option(name)

Return the value of a particular option in the OptionList.

Parameters:name (str) – name of the option to retrieve Returns:value associated with the passed option Return type:str

get_options()

Return the whole bunch of options for the OptionList.

Returns:list of options Return type:list

remove_option(name)

Remove a particular option from the OptionList.

Parameters:name (str) – name of the option to remove.

set_option(name, value)

Set a particular option in the OptionList.

Parameters:

• name (str) – name of the option to set.
• value (str) – value of the option to set.

set_options(options)

Set the whole bunch of options for the OptionList.

Parameters:options (list) – list of options to set.

class gramps.gen.plug._options.OptionListCollection(filename)

Bases: object

Implements a collection of option lists.

get_module_names()

Return a list of all the module names in the OptionListCollection

Returns:returns the list of module names Return type:list

get_option_list(name)

Return the option_list associated with the module name

Parameters:name (str) – name associated with the desired module. Returns:returns the option list associated with the name, or None of no such option exists Return type:str

get_option_list_map()

Return the map of module names to option lists.

Returns:Returns the map of module names to option lists. Return type:dictionary

init_common()

parse()

Loads the OptionList from the associated file, if it exists.

save()

Saves the current OptionListCollection to the associated file.

set_option_list(name, option_list)

Add or replaces an option_list in the OptionListCollection.

Parameters:

• name (str) – name associated with the module to add or replace.
• option_list (OptionList) – list of options

write_common(f)

Stub function for common options. Overridden by reports.

write_module_common(f, option_list)

Stub function for common options. Overridden by reports.

class gramps.gen.plug._options.OptionParser(collection)

Bases: xml.sax.handler.ContentHandler

SAX parsing class for the OptionListCollection XML file.

endElement(tag)

Overridden class that handles the end of a XML element

startElement(tag, attrs)

Overridden class that handles the start of a XML element

class gramps.gen.plug._options.Options(name, person_id=None)

Bases: object

Defines options and provides handling interface.

This is a base Options class for the modules. All modules, options classes should derive from it.

add_user_options()

Set up UI controls (widgets) for the options specific for this module.

This method MUST be overridden by modules that define new options.

Note

To really have any effect besides looking pretty, each widget set up here must be also parsed in the parse_user_options() method below.

load_previous_values()

Modifies all options to have the value they were last used as. Call this function after all options have been added.

parse_user_options()

Parses UI controls (widgets) for the options specific for this module.

This method MUST be overridden by modules that define new options.

After obtaining values from the widgets, they MUST be used to set the appropriate options_dict values. Otherwise the values will not have any user-visible effect.

Note

Any widget parsed here MUST be defined and added to the dialog in the add_user_options() method above.

Reports

Report option handling, including saving and parsing.

class gramps.gen.plug.report._options.DocOptionHandler(module_name, options_dict)

Bases: gramps.gen.plug._options.OptionHandler

Implements handling of the docgen options for the plugins.

init_subclass()

set_options()

Set options to be used in this plugin according to the passed options dictionary.

Dictionary values are all strings, since they were read from XML. Here we need to convert them to the needed types. We use default values to determine the type.

class gramps.gen.plug.report._options.DocOptionListCollection(filename)

Bases: gramps.gen.plug._options.OptionListCollection

Implements a collection of option lists.

init_common()

parse()

Loads the OptionList from the associated file, if it exists.

class gramps.gen.plug.report._options.DocOptionParser(collection)

Bases: gramps.gen.plug._options.OptionParser

SAX parsing class for the DocOptionListCollection XML file.

endElement(tag)

Overridden class that handles the end of a XML element

startElement(tag, attrs)

Overridden class that handles the start of a XML element

class gramps.gen.plug.report._options.DocOptions(name)

Bases: gramps.gen.plug._options.MenuOptions

Defines options and provides handling interface.

load_previous_values()

class gramps.gen.plug.report._options.EmptyDoc

Bases: object

close()

init()

open(filename)

set_creator(creator)

class gramps.gen.plug.report._options.MenuReportOptions(name, dbase)

Bases: gramps.gen.plug._options.MenuOptions, gramps.gen.plug.report._options.ReportOptions

The MenuReportOptions class implements the ReportOptions functionality in a generic way so that the user does not need to be concerned with the actual representation of the options.

The user should inherit the MenuReportOptions class and override the add_menu_options function. The user can add options to the menu and the MenuReportOptions class will worry about setting up the UI.

load_previous_values()

class gramps.gen.plug.report._options.OptionHandler(module_name, options_dict)

Bases: gramps.gen.plug._options.OptionHandler

Implements handling of the options for the plugins.

get_css_filename()

get_custom_paper_size()

get_default_stylesheet_name()

get_format_name()

get_margins()

get_orientation()

get_paper()

This method is for temporary storage, not for saving/restoring.

get_paper_metric()

get_paper_name()

get_stylesheet_savefile()

Where to save user defined styles for this report.

init_common()

Specific initialization for reports.

init_subclass()

save_common_options()

save_options()

Saves options to file.

set_common_options()

set_css_filename(css_filename)

set_custom_paper_size(custom_paper_size)

set_default_stylesheet_name(style_name)

set_format_name(format_name)

set_margins(margins)

set_orientation(orientation)

set_paper(paper)

This method is for temporary storage, not for saving/restoring.

set_paper_metric(paper_metric)

set_paper_name(paper_name)

class gramps.gen.plug.report._options.OptionList

Bases: gramps.gen.plug._options.OptionList

Implements a set of options to parse and store for a given report.

get_css_filename()

Return the template name of the OptionList.

Returns:template name Return type:str

get_custom_paper_size()

Return the custom paper size for the OptionList.

Returns:returns the custom paper size in cm Return type:[float, float]

get_format_name()

Return the format name of the OptionList.

Returns:returns the format name Return type:str

get_margin(pos)

Return a margin for the OptionList.

Parameters:pos (int) – Position of margin [left, right, top, bottom] Returns:float cm of margin Return type:float

get_margins()

Return the margins for the OptionList.

Returns margins:  returns the margins, floats in cm Rtype margins:[float, float, float, float]

get_orientation()

Return the orientation for the OptionList.

Returns:returns the selected orientation. Valid values are PAPER_LANDSCAPE or PAPER_PORTRAIT Return type:int

get_output()

Return the output of the OptionList.

Returns:returns the output name Return type:str

get_paper_metric()

Return the paper metric of the OptionList.

Returns:returns whether to use metric Return type:boolean

get_paper_name()

Return the paper name of the OptionList.

Returns:returns the paper name Return type:str

get_style_name()

Return the style name of the OptionList.

Returns:string representing the style name Return type:str

set_css_filename(css_filename)

Set the template name for the OptionList.

Parameters:template_name (str) – name of the template to set.

set_custom_paper_size(paper_size)

Set the custom paper size for the OptionList.

Parameters:paper_size ([float, float]) – paper size to set in cm.

set_format_name(format_name)

Set the format name for the OptionList.

Parameters:format_name (str) – name of the format to set.

set_margin(pos, value)

Set a margin for the OptionList.

Parameters:

• pos (int) – Position of margin [left, right, top, bottom]
• value (float) – floating point in cm

set_margins(margins)

Set the margins for the OptionList.

Parameters:margins ([float, float, float, float]) – margins to set. Possible values are floats in cm

set_orientation(orientation)

Set the orientation for the OptionList.

Parameters:orientation (int) – orientation to set. Possible values are PAPER_LANDSCAPE or PAPER_PORTRAIT

set_output(output)

Set the output for the OptionList.

Parameters:output (str) – name of the output to set.

set_paper_metric(paper_metric)

Set the paper metric for the OptionList.

Parameters:paper_metric – whether to use metric.

set_paper_name(paper_name)

Set the paper name for the OptionList.

Parameters:paper_name (str) – name of the paper to set.

set_style_name(style_name)

Set the style name for the OptionList.

Parameters:style_name (str) – name of the style to set.

class gramps.gen.plug.report._options.OptionListCollection(filename)

Bases: gramps.gen.plug._options.OptionListCollection

Implements a collection of option lists.

get_last_css_filename()

Return the last template used for any report in this collection.

get_last_custom_paper_size()

Return the last custom paper size used for any report in this collection.

Returns:list of last custom paper size used in cm (width, height) Return type:[float, float]

get_last_format_name()

Return the last format used for any report in this collection.

get_last_margin(pos)

Return the last margins used for any report in this collection.

Parameters:pos (int) – position in margins list Returns:last margin used in pos Return type:float

get_last_margins()

Return the last margins used for any report in this collection.

Returns:list of last margins used in cm (left, right, top, bottom) Return type:[float, float, float, float]

get_last_orientation()

Return the last orientation used for any report in this collection.

Returns:last orientation used Return type:int

get_last_paper_metric()

Return the last paper metric used for any report in this collection.

Returns:returns whether or not to use metric Return type:boolean

get_last_paper_name()

Return the last paper name used for any report in this collection.

Returns:returns the name of the paper Return type:str

init_common()

parse()

Loads the OptionList from the associated file, if it exists.

set_last_css_filename(css_filename)

Set the last css used for any report in this collection.

Parameters:css_filename – name of the style to set.

set_last_custom_paper_size(custom_paper_size)

Set the last custom paper size used for any report in this collection.

Parameters:custom_paper_size ([float, float]) – size to set in cm (width, height)

set_last_format_name(format_name)

Set the last format used for any report in this collection.

Parameters:format_name – name of the format to set.

set_last_margin(pos, value)

Set the last margin used for any report in this collection.

Parameters:

• pos (int) – pos to set (0-4) (left, right, top, bottom)
• value (float) – value to set the margin to in cm

set_last_margins(margins)

Set the last margins used for any report in this collection.

Parameters:margins ([float, float, float, float]) – margins to set in cm (left, right, top, bottom)

set_last_orientation(orientation)

Set the last orientation used for any report in this collection.

Parameters:orientation (int) – orientation to set.

set_last_paper_metric(paper_metric)

Set the last paper metric used for any report in this collection.

Parameters:paper_metric – whether to use metric.

set_last_paper_name(paper_name)

Set the last paper name used for any report in this collection.

Parameters:paper_name (str) – name of the paper to set.

write_common(f)

write_module_common(f, option_list)

class gramps.gen.plug.report._options.OptionParser(collection)

Bases: gramps.gen.plug._options.OptionParser

SAX parsing class for the OptionListCollection XML file.

endElement(tag)

Overridden class that handles the end of a XML element

startElement(tag, attrs)

Overridden class that handles the start of a XML element

class gramps.gen.plug.report._options.ReportOptions(name, dbase)

Bases: gramps.gen.plug._options.Options

Defines options and provides handling interface.

This is a base Options class for the reports. All reports, options classes should derive from it.

get_document()

Return document instance.

Warning

This method MUST NOT be overridden by subclasses.

get_output()

Return document output destination.

Warning

This method MUST NOT be overridden by subclasses.

load_previous_values()

make_default_style(default_style)

Defines default style for this report.

This method MUST be overridden by reports that use the user-adjustable paragraph styles.

Note

Unique names MUST be used for all style names, otherwise the styles will collide when making a book with duplicate style names. A rule of safety is to prepend style name with the acronym based on report name.

The following acronyms are already taken:

Code	Report
AC	Ancestor Chart
AC2	Ancestor Chart 2 (Wall Chart)
AHN	Ahnentafel Report
AR	Comprehensive Ancestors report
CBT	Custom Book Text
DG	Descendant Graph
DR	Descendant Report
DAR	Detailed Ancestral Report
DDR	Detailed Descendant Report
FGR	Family Group Report
FC	Fan Chart
FTA	FTM Style Ancestral report
FTD	FTM Style Descendant report
IDS	Individual Complete Report
IDX	Alphabetical Index
IVS	Individual Summary Report
PLC	Place Report
SBT	Simple Book Title
TLG	Timeline Graph
TOC	Table Of Contents

set_document(val)

Set document to a given instance.

Warning

This method MUST NOT be overridden by subclasses.

set_output(val)

Set output destination to a given string.

Warning

This method MUST NOT be overridden by subclasses.

gramps.gen.plug.report._options.escxml(d)

Contain and organize bibliographic information.

class gramps.gen.plug.report._bibliography.Bibliography(mode=31)

Bases: object

Store and organize multiple citations into a bibliography.

MODE_ALL = 31

MODE_CONF = 4

MODE_DATE = 1

MODE_MEDIA = 16

MODE_NOTE = 8

MODE_PAGE = 2

add_reference(lib_citation)

Add a reference to a source to this bibliography. If the source already exists, don’t add it again. If a similar reference exists, don’t add another one.

Parameters:citation (Citation) – Citation object Returns:A tuple containing the index of the source among all the sources and the key of the reference among all the references. If there is no reference information, the second element will be None. Return type:(int,char) or (int,None)

Note

Within this file, the name ‘citation’ is used both for gen.lib.Citation, and for _bibliography.Citation. It is not clear how best to rename the concepts in this file to avoid the clash, so the names have been retained. In this function, lib_citation is used for gen.lib.Citation instances, and citation for _bibliography.Citation instances. Elsewhere in this file, source_ref is used for gen.lib.Citation instances.

get_citation_count()

Report the number of citations in this bibliography.

Returns:number of citations Return type:int

get_citation_list()

Return a list containing all the citations in this bibliography.

Returns:citation list Return type:list of Citation objects

class gramps.gen.plug.report._bibliography.Citation

Bases: object

Store information about a citation and all of its references.

add_reference(source_ref)

Add a reference to this citation. If a similar reference exists, don’t add another one.

Parameters:source_ref (Citation) – Source Reference Returns:The key of the added reference among all the references. Return type:char

get_ref_list()

List all the references to this citation.

Returns:a list of references Return type:list of Citation objects

get_source_handle()

Provide the handle to the source that this citation is for.

Returns:Source Handle Return type:handle

set_source_handle(handle)

Set the handle for the source that this citation is for.

Parameters:handle (handle) – Source Handle

Report Generation Framework

Provide utilities for printing endnotes in text reports.

gramps.gen.plug.report.endnotes.add_endnote_styles(style_sheet)

Add paragraph styles to a style sheet to be used for displaying endnotes.

Parameters:style_sheet (StyleSheet) – Style sheet

gramps.gen.plug.report.endnotes.cite_source(bibliography, database, obj)

Cite any sources for the object and add them to the bibliography.

Parameters:

• bibliography (Bibliography) – The bibliography to contain the citations.
• obj (CitationBase) – An object with source references.

gramps.gen.plug.report.endnotes.write_endnotes(bibliography, database, doc, printnotes=False, links=False, elocale=<gramps.gen.utils.grampslocale.GrampsLocale object at 0x2b07d2b06f10>)

Write all the entries in the bibliography as endnotes.

If elocale is passed in (a GrampsLocale), then (insofar as possible) the translated values will be returned instead.

Parameters:

• bibliography (Bibliography) – The bibliography that contains the citations.
• database (DbBase) – The database that the sources come from.
• doc (TextDoc) – The document to write the endnotes into.
• printnotes (bool) – Indicate if the notes attached to a source must be written too.
• links (bool) – Indicate if URL links should be makde ‘clickable’.
• elocale (a GrampsLocale instance) – allow deferred translation of dates and strings

class gramps.gen.plug.report._paper.PageSizeParser(paper_list)

Bases: xml.sax.handler.ContentHandler

Parses the XML file and builds the list of page sizes

setDocumentLocator(locator)

startElement(tag, attrs)

class gramps.gen.plug.report._reportbase.Report(database, options_class, user)

Bases: object

The Report base class. This is a base class for generating customized reports. It cannot be used as is, but it can be easily sub-classed to create a functional report generator.

begin_report()

end_report()

set_locale(language)

Set the translator to one selected with stdoptions.add_localization_option().

write_report()

A collection of utilities to aid in the generation of reports.

gramps.gen.plug.report.utils.cm2pt(cm)

Convert centimeters to points. Fonts are typically specified in points, but the BaseDoc classes use centimeters.

Parameters:cm (float or int) – centimeters Returns:equivalent units in points Return type:float

gramps.gen.plug.report.utils.find_marriage(database, family)

gramps.gen.plug.report.utils.find_spouse(person, family)

gramps.gen.plug.report.utils.get_address_str(addr)

Return a string that combines the elements of an address

Parameters:addr – the Gramps address instance

gramps.gen.plug.report.utils.get_person_filters(person, include_single=True)

Return a list of filters that are relevant for the given person

Parameters:

• person (Person) – the person the filters should apply to.
• include_single (boolean) – include a filter to include the single person

gramps.gen.plug.report.utils.get_person_mark(db, person)

Return a IndexMark that can be used to index a person in a report

Parameters:

• db – the Gramps database instance
• person – the key is for

gramps.gen.plug.report.utils.insert_image(database, doc, photo, user, w_cm=4.0, h_cm=4.0, alt='')

Insert pictures of a person into the document.

gramps.gen.plug.report.utils.place_name(db, place_handle)

gramps.gen.plug.report.utils.pt2cm(pt)

Convert points to centimeters. Fonts are typically specified in points, but the BaseDoc classes use centimeters.

Parameters:pt (float or int) – points Returns:equivalent units in centimeters Return type:float

gramps.gen.plug.report.utils.rgb_color(color)

Convert color value from 0-255 integer range into 0-1 float range.

Parameters:color (int) – list or tuple of integer values for red, green, and blue Returns:(r, g, b) tuple of floating point color values Return type:3-tuple

gramps.gen.plug.report.utils.roman(num)

Integer to Roman numeral converter for 0 < num < 4000

Docgen

This module provides the Plugin class for document generator plugins.

class gramps.gen.plug._docgenplugin.DocGenPlugin(name, description, basedoc, paper, style, extension, docoptclass, basedocname)

Bases: gramps.gen.plug._plugin.Plugin

This class represents a plugin for generating documents from Gramps

get_basedoc()

Get the BaseDoc class for this plugin.

Returns:the BaseDoc class passed into __init__()

get_basedocname()

Get the BaseDoc name for this plugin.

Returns:the BaseDoc name passed into __init__()

get_doc_option_class()

Get the DocOptions subclass for this plugin, if any

Returns:the DocOptions subclass passed into __init__()

get_draw_support()

Check if the plugin supports the DrawDoc interface.

Returns:bool: True if DrawDoc is supported; False if DrawDoc is not supported.

get_extension()

Get the file extension for the output file.

Returns:str

get_paper_used()

Get the paper flag for this plugin.

Returns:bool - True = use paper; False = do not use paper

get_style_support()

Get the style flag for this plugin.

Returns:bool - True = use styles; False = do not use styles

get_text_support()

Check if the plugin supports the TextDoc interface.

Returns:bool: True if TextDoc is supported; False if TextDoc is not supported.

Generators

Provide base interface to text based documents. Specific document interfaces should be derived from the core classes.

class gramps.gen.plug.docgen.basedoc.BaseDoc(styles, paper_style)

Bases: object

Base class for document generators. Different output formats, such as OpenOffice, AbiWord, and LaTeX are derived from this base class, providing a common interface to all document generators.

close()

Closes the generated file.

get_creator()

Return the owner name

get_style_sheet()

Return the StyleSheet of the document.

init()

open(filename)

Opens the file so that it can be generated.

Parameters:filename – path name of the file to create

set_creator(name)

Set the owner name

set_style_sheet(style_sheet)

Set the StyleSheet of the document.

Parameters:style_sheet (StyleSheet) – The new style sheet for the document

class gramps.gen.plug.docgen.drawdoc.DrawDoc

Bases: object

Abstract Interface for graphical document generators. Output formats for graphical reports must implement this interface to be used by the report system.

center_text(style, text, x1, y1, mark=None)

Parameters:mark – IndexMark to use for indexing (if supported)

draw_box(style, text, x, y, w, h, mark=None)

Parameters:mark – IndexMark to use for indexing (if supported)

draw_line(style, x1, y1, x2, y2)

draw_path(style, path)

draw_text(style, text, x1, y1, mark=None)

Parameters:mark – IndexMark to use for indexing (if supported)

end_page()

get_usable_height()

Return the height of the text area in centimeters. The value is the page height less the margins.

get_usable_width()

Return the width of the text area in centimeters. The value is the page width less the margins.

rotate_text(style, text, x, y, angle, mark=None)

Parameters:mark – IndexMark to use for indexing (if supported)

start_page()

string_multiline_width(fontstyle, text)

Determine the width need for multiline text in given font

string_width(fontstyle, text)

Determine the width need for text in given font

Provide a rough estimate of the width of a text string.

gramps.gen.plug.docgen.fontscale.string_multiline_width(font, text)

gramps.gen.plug.docgen.fontscale.string_trim(font, text, width, ellipses='...')

Like string_width, but this makes sure the length of the string is <= width. Optionally, add ellipses (...).

gramps.gen.plug.docgen.fontscale.string_width(font, text)

returns with width of a string in the specified font

class gramps.gen.plug.docgen.fontstyle.FontStyle(style=None)

Bases: object

Defines a font style. Controls the font face, size, color, and attributes. In order to remain generic, the only font faces available are FONT_SERIF and FONT_SANS_SERIF. Document formatters should convert these to the appropriate fonts for the target format.

The FontStyle represents the desired characteristics. There are no guarentees that the document format generator will be able implement all or any of the characteristics.

get_bold()

1 indicates use bold face

get_color()

Return an RGB color tuple

get_italic()

1 indicates use italics

get_size()

returns font size in points

get_type_face()

returns the font face type

get_underline()

1 indicates underlining

set(face=None, size=None, italic=None, bold=None, underline=None, color=None)

Set font characteristics.

Parameters:

• face – font type face, either FONT_SERIF or FONT_SANS_SERIF
• size – type face size in points
• italic – True enables italics, False disables italics
• bold – True enables bold face, False disables bold face
• underline – True enables underline, False disables underline
• color – an RGB color representation in the form of three integers in the range of 0-255 represeting the red, green, and blue components of a color.

set_bold(val)

0 disables bold face, 1 enables bold face

set_color(val)

sets the color using an RGB color tuple

set_italic(val)

0 disables italics, 1 enables italics

set_size(val)

sets font size in points

set_type_face(val)

sets the font face type

set_underline(val)

1 enables underlining

class gramps.gen.plug.docgen.graphdoc.GVDoc

Bases: object

Abstract Interface for Graphviz document generators. Output formats for Graphviz reports must implement this interface to be used by the report system.

add_comment(comment)

Add a comment to the source file.

Parameters:comment (string) – A text string to add as a comment. Example: “Next comes the individuals.” Returns:nothing

add_link(id1, id2, style=u'', head=u'', tail=u'', comment=u'')

Add a link between two nodes.

Parameters:

• id1 (string) – The unique identifier of the starting node. Example: “p55”
• id2 (string) – The unique identifier of the ending node. Example: “p55”
• comment (string) – A text string displayed at the end of the link line. Example: “person C is the son of person A and person B”

Returns:

nothing

add_node(node_id, label, shape=u'', color=u'', style=u'', fillcolor=u'', url=u'', htmloutput=False)

Add a node to this graph. Nodes can be different shapes like boxes and circles.

Parameters:

• node_id (string) – A unique identification value for this node. Example: “p55”
• label (string) – The text to be displayed in the node. Example: “John Smith”
• shape (string) – The shape for the node. Examples: “box”, “ellipse”, “circle”
• color (string) – The color of the node line. Examples: “blue”, “lightyellow”
• style (string) – The style of the node.
• fillcolor (string) – The fill color for the node. Examples: “blue”, “lightyellow”
• url (string) – A URL for the node.
• htmloutput (boolean) – Whether the label contains HTML.

Returns:

nothing

end_subgraph()

End a subgraph that was previously started in this graph.

Returns:nothing

start_subgraph(graph_id)

Start a subgraph in this graph.

Parameters:id – The unique identifier of the subgraph. Example: “p55” Returns:nothing

class gramps.gen.plug.docgen.graphdoc.GVDocBase(options, paper_style)

Bases: gramps.gen.plug.docgen.basedoc.BaseDoc, gramps.gen.plug.docgen.graphdoc.GVDoc

Base document generator for all Graphviz document generators. Classes that inherit from this class will only need to implement the close function. The close function will generate the actual file of the appropriate type.

add_comment(comment)

Add a comment.

Implements GVDocBase.add_comment().

add_link(id1, id2, style=u'', head=u'', tail=u'', comment=u'')

Add a link between two nodes.

Implements GVDocBase.add_link().

add_node(node_id, label, shape=u'', color=u'', style=u'', fillcolor=u'', url=u'', htmloutput=False)

Add a node to this graph. Nodes can be different shapes like boxes and circles.

Implements GVDocBase.add_node().

close()

This isn’t useful by itself. Other classes need to override this and actually generate a file.

end_subgraph()

Implement GVDocBase.end_subgraph()

open(filename)

Implement GVDocBase.open()

start_subgraph(graph_id)

Implement GVDocBase.start_subgraph()

write(text)

Write text to the dot file

class gramps.gen.plug.docgen.graphdoc.GVDotDoc(options, paper_style)

Bases: gramps.gen.plug.docgen.graphdoc.GVDocBase

GVDoc implementation that generates a .gv text file.

close()

Implements GVDotDoc.close()

class gramps.gen.plug.docgen.graphdoc.GVGifDoc(options, paper_style)

Bases: gramps.gen.plug.docgen.graphdoc.GVDocBase

GVDoc implementation that generates a .gif file using Graphviz.

close()

Implements GVGifDoc.close()

class gramps.gen.plug.docgen.graphdoc.GVJpegDoc(options, paper_style)

Bases: gramps.gen.plug.docgen.graphdoc.GVDocBase

GVDoc implementation that generates a .jpg file using Graphviz.

close()

Implements GVJpegDoc.close()

class gramps.gen.plug.docgen.graphdoc.GVOptions

Defines all of the controls necessary to configure the graph reports.

add_menu_options(menu)

Add all graph related options to the menu.

Parameters:menu (Menu) – The menu the options should be added to. Returns:nothing

pages_changed()

This method gets called every time the v_pages or h_pages options are changed; when both vertical and horizontal pages are set to “1”, then the page_dir control needs to be unavailable

class gramps.gen.plug.docgen.graphdoc.GVPdfGsDoc(options, paper_style)

Bases: gramps.gen.plug.docgen.graphdoc.GVDocBase

GVDoc implementation that generates a .pdf file using Ghostscript.

close()

Implements GVPdfGsDoc.close()

class gramps.gen.plug.docgen.graphdoc.GVPdfGvDoc(options, paper_style)

Bases: gramps.gen.plug.docgen.graphdoc.GVDocBase

GVDoc implementation that generates a .pdf file using Graphviz.

close()

Implements GVPdfGvDoc.close()

class gramps.gen.plug.docgen.graphdoc.GVPngDoc(options, paper_style)

Bases: gramps.gen.plug.docgen.graphdoc.GVDocBase

GVDoc implementation that generates a .png file using Graphviz.

close()

Implements GVPngDoc.close()

class gramps.gen.plug.docgen.graphdoc.GVPsDoc(options, paper_style)

Bases: gramps.gen.plug.docgen.graphdoc.GVDocBase

GVDoc implementation that generates a .ps file using Graphviz.

close()

Implements GVPsDoc.close()

class gramps.gen.plug.docgen.graphdoc.GVSvgDoc(options, paper_style)

Bases: gramps.gen.plug.docgen.graphdoc.GVDocBase

GVDoc implementation that generates a .svg file using Graphviz.

close()

Implements GVSvgDoc.close()

class gramps.gen.plug.docgen.graphdoc.GVSvgzDoc(options, paper_style)

Bases: gramps.gen.plug.docgen.graphdoc.GVDocBase

GVDoc implementation that generates a .svg file using Graphviz.

close()

Implements GVSvgzDoc.close()

class gramps.gen.plug.docgen.graphicstyle.GraphicsStyle(obj=None)

Bases: object

Defines the properties of graphics objects, such as line width, color, fill, ect.

get_color()

get_dash_style(val=None)

get_dash_style_name(val=None)

get_fill_color()

get_line_style()

get_line_width()

Return the name of the StyleSheet

get_paragraph_style()

get_shadow()

get_shadow_space()

set_color(val)

set_fill_color(val)

set_line_style(val)

set_line_width(val)

sets the line width

set_paragraph_style(val)

set_shadow(val, space=0.2)

gramps.gen.plug.docgen.graphicstyle.get_line_style_by_name(style_name)

class gramps.gen.plug.docgen.paperstyle.PaperSize(name, height, width)

Bases: object

Defines the dimensions of a sheet of paper. All dimensions are in centimeters.

get_height()

Return the page height in cm

get_height_inches()

Return the page height in inches

get_name()

Return the name of the paper style

get_width()

Return the page width in cm

get_width_inches()

Return the page width in inches

set_height(height)

Set the page height in cm

set_width(width)

Set the page width in cm

class gramps.gen.plug.docgen.paperstyle.PaperStyle(size, orientation, lmargin=2.54, rmargin=2.54, tmargin=2.54, bmargin=2.54)

Bases: object

Define the various options for a sheet of paper.

get_bottom_margin()

Return the bottom margin.

Returns:Bottom margin in centimeters Return type:float

get_left_margin()

Return the left margin.

Returns:Left margin in centimeters Return type:float

get_orientation()

Return the orientation of the page.

Returns:PAPER_PORTRIAT or PAPER_LANDSCAPE Return type:int

get_right_margin()

Return the right margin.

Returns:Right margin in centimeters Return type:float

get_size()

Return the size of the paper.

Returns:object indicating the paper size Return type:PaperSize

get_top_margin()

Return the top margin.

Returns:Top margin in centimeters Return type:float

get_usable_height()

Return the height of the page area in centimeters.

The value is the page height less the margins.

get_usable_width()

Return the width of the page area in centimeters.

The value is the page width less the margins.

class gramps.gen.plug.docgen.paragraphstyle.ParagraphStyle(source=None)

Bases: object

Defines the characteristics of a paragraph. The characteristics are: font (a FontStyle instance), right margin, left margin, first indent, top margin, bottom margin, alignment, level, top border, bottom border, right border, left border, padding, and background color.

get_alignment()

Return the alignment of the paragraph

get_alignment_text()

Return a text string representing the alignment, either ‘left’, ‘right’, ‘center’, or ‘justify’

get_background_color()

Return a tuple indicating the RGB components of the background color

get_bottom_border()

Return 1 if a bottom border is specified

get_bottom_margin()

returns the space below paragraph in centimeters

get_description()

Return the desciption of the paragraph

get_first_indent()

returns the first line indent in centimeters

get_font()

Return the FontStyle of the paragraph

get_header_level()

Return the header level of the paragraph

get_left_border()

Return 1 if a left border is specified

get_left_margin()

returns the left indent in centimeters

get_padding()

Return a the padding of the paragraph

get_right_border()

Return 1 if a right border is specified

get_right_margin()

returns the right indent in centimeters

get_tabs()

get_top_border()

Return 1 if a top border is specified

get_top_margin()

returns the space above paragraph in centimeters

set(rmargin=None, lmargin=None, first_indent=None, tmargin=None, bmargin=None, align=None, tborder=None, bborder=None, rborder=None, lborder=None, pad=None, bgcolor=None, font=None)

Allows the values of the object to be set.

Parameters:

• rmargin – right indent in centimeters
• lmargin – left indent in centimeters
• first_indent – first line indent in centimeters
• tmargin – space above paragraph in centimeters
• bmargin – space below paragraph in centimeters
• align – alignment type (PARA_ALIGN_LEFT, PARA_ALIGN_RIGHT, PARA_ALIGN_CENTER, or PARA_ALIGN_JUSTIFY)
• tborder – non zero indicates that a top border should be used
• bborder – non zero indicates that a bottom border should be used
• rborder – non zero indicates that a right border should be used
• lborder – non zero indicates that a left border should be used
• pad – padding in centimeters
• bgcolor – background color of the paragraph as an RGB tuple.
• font – FontStyle instance that defines the font

set_alignment(align)

Set the paragraph alignment.

Parameters:align – PARA_ALIGN_LEFT, PARA_ALIGN_RIGHT, PARA_ALIGN_CENTER, or PARA_ALIGN_JUSTIFY

set_background_color(color)

Set the background color of the paragraph.

Parameters:color – tuple representing the RGB components of a color (0,0,0) to (255,255,255)

set_bottom_border(val)

Set the presence or absence of bottom border.

Parameters:val – True indicates a border should be used, False indicates no border.

set_bottom_margin(value)

sets the space below paragraph in centimeters

set_description(text)

Set the desciption of the paragraph

set_first_indent(value)

sets the first line indent in centimeters

set_font(font)

Set the font style of the paragraph.

Parameters:font – FontStyle object containing the font definition to use.

set_header_level(level)

Set the header level for the paragraph. This is useful for numbered paragraphs. A value of 1 indicates a header level format of X, a value of two implies X.X, etc. A value of zero means no header level.

set_left_border(val)

Set the presence or absence of left border.

Parameters:val – True indicates a border should be used, False indicates no border.

set_left_margin(value)

sets the left indent in centimeters

set_padding(val)

Set the paragraph padding in centimeters

Parameters:val – floating point value indicating the padding in centimeters

set_right_border(val)

Set the presence or absence of rigth border.

Parameters:val – True indicates a border should be used, False indicates no border.

set_right_margin(value)

sets the right indent in centimeters

set_tabs(tab_stops)

set_top_border(val)

Set the presence or absence of top border.

Parameters:val – True indicates a border should be used, False indicates no border.

set_top_margin(value)

sets the space above paragraph in centimeters

class gramps.gen.plug.docgen.stylesheet.SheetParser(sheetlist)

Bases: xml.sax.handler.ContentHandler

SAX parsing class for the StyleSheetList XML file.

endElement(tag)

Overridden class that handles the start of a XML element

startElement(tag, attrs)

Overridden class that handles the start of a XML element

class gramps.gen.plug.docgen.stylesheet.StyleSheet(obj=None)

Bases: object

A collection of named paragraph styles.

add_cell_style(name, style)

Add a cell style to the style sheet.

Parameters:

• name – The name of the TableCellStyle
• style – TableCellStyle instance to be added.

add_draw_style(name, style)

Add a draw style to the style sheet.

Parameters:

• name – The name of the GraphicsStyle
• style – GraphicsStyle instance to be added.

add_paragraph_style(name, style)

Add a paragraph style to the style sheet.

Parameters:

• name – The name of the ParagraphStyle
• style – ParagraphStyle instance to be added.

add_table_style(name, style)

Add a table style to the style sheet.

Parameters:

• name – The name of the TableStyle
• style – TableStyle instance to be added.

clear()

Remove all styles from the StyleSheet

get_cell_style(name)

Return the TableCellStyle associated with the name

Parameters:name – name of the TableCellStyle that is wanted

get_cell_style_names()

Return the list of cell style names in the StyleSheet

get_draw_style(name)

Return the GraphicsStyle associated with the name

Parameters:name – name of the GraphicsStyle that is wanted

get_draw_style_names()

Return the list of draw style names in the StyleSheet

get_name()

Return the name of the StyleSheet

get_paragraph_style(name)

Return the ParagraphStyle associated with the name

Parameters:name – name of the ParagraphStyle that is wanted

get_paragraph_style_names()

Return the list of paragraph names in the StyleSheet

get_table_style(name)

Return the TableStyle associated with the name

Parameters:name – name of the TableStyle that is wanted

get_table_style_names()

Return the list of table style names in the StyleSheet

is_empty()

Checks if any styles are defined

set_name(name)

Set the name of the StyleSheet

Parameters:name – The name to be given to the StyleSheet

class gramps.gen.plug.docgen.stylesheet.StyleSheetList(filename, defstyle)

Bases: object

Interface into the user’s defined style sheets. Each StyleSheetList has a predefined default style specified by the report. Additional styles are loaded from a specified XML file if it exists.

delete_style_sheet(name)

Remove a style from the list. Since each style must have a unique name, the name is used to delete the stylesheet.

name - Name of the style to delete

get_style_names()

Return a list of all the style names in the StyleSheetList

get_style_sheet(name)

Return the StyleSheet associated with the name

name - name associated with the desired StyleSheet.

get_style_sheet_map()

Return the map of names to styles.

parse()

Loads the StyleSheets from the associated file, if it exists.

save()

Saves the current StyleSheet definitions to the associated file.

set_style_sheet(name, style)

Add or replaces a StyleSheet in the StyleSheetList. The default style may not be replaced.

name - name associated with the StyleSheet to add or replace. style - definition of the StyleSheet

gramps.gen.plug.docgen.stylesheet.cnv2color(text)

converts a hex value in the form of #XXXXXX into a tuple of integers representing the RGB values

gramps.gen.plug.docgen.stylesheet.escxml(string)

Escapes XML special characters.

class gramps.gen.plug.docgen.tablestyle.TableCellStyle(obj=None)

Bases: object

Defines the style of a particular table cell. Characteristics are: right border, left border, top border, bottom border, and padding.

get_bottom_border()

Return 1 if a bottom border is requested

get_left_border()

Return 1 if a left border is requested

get_longlist()

get_padding()

Return the cell padding in centimeters

get_right_border()

Return 1 if a right border is requested

get_top_border()

Return 1 if a top border is requested

set_borders(val)

Defines if a border is used

Parameters:val – if True, a border is used, if False, it is not

set_bottom_border(val)

Defines if a bottom border in used

Parameters:val – if 1, a bottom border is used, if 0, it is not

set_left_border(val)

Defines if a left border in used

Parameters:val – if True, a left border is used, if False, it is not

set_longlist(val)

set_padding(val)

Return the cell padding in centimeters

set_right_border(val)

Defines if a right border in used

Parameters:val – if True, a right border is used, if False, it is not

set_top_border(val)

Defines if a top border in used

Parameters:val – if True, a top border is used, if False, it is not

class gramps.gen.plug.docgen.tablestyle.TableStyle(obj=None)

Bases: object

Specifies the style or format of a table. The TableStyle contains the characteristics of table width (in percentage of the full width), the number of columns, and the width of each column as a percentage of the width of the table.

get_column_width(index)

Return the column width of the specified column as a percentage of the entire table width.

Parameters:index – column to return (index starts at 0)

get_columns()

Return the number of columns

get_width()

Return the specified width as a percentage of the available space

set_column_width(index, width)

Set the width of a specified column to the specified width.

Parameters:

• index – column being set (index starts at 0)
• width – percentage of the table width assigned to the column

set_column_widths(clist)

Set the width of all the columns at once, taking the percentages from the passed list.

set_columns(columns)

Set the number of columns.

Parameters:columns – number of columns that should be used.

set_width(width)

Set the width of the table in terms of percent of the available width

class gramps.gen.plug.docgen.textdoc.IndexMark(key='', itype=0, level=1)

Bases: object

Defines a mark to be associated with text for indexing.

class gramps.gen.plug.docgen.textdoc.TextDoc

Bases: object

Abstract Interface for text document generators. Output formats for text reports must implement this interface to be used by the report system.

add_media_object(name, align, w_cm, h_cm, alt='', style_name=None, crop=None)

Add a photo of the specified width (in centimeters).

Parameters:

• name – filename of the image to add
• align – alignment of the image. Valid values are ‘left’, ‘right’, ‘center’, and ‘single’
• w_cm – width in centimeters
• h_cm – height in centimeters
• alt – an alternative text to use. Useful for eg html reports
• style_name – style to use for captions
• crop – image cropping parameters

end_bold()

end_cell()

Ends the current table cell.

end_paragraph()

Ends the current paragraph.

end_row()

Ends the current row on the current table.

end_superscript()

end_table()

Ends the current table

insert_index()

Insert an Alphabetical Index at this point in the document. This passes without error so that docgen types are not required to have this.

insert_toc()

Insert a Table of Contents at this point in the document. This passes without error so that docgen types are not required to have this.

page_break()

Forces a page break, creating a new page.

start_bold()

start_cell(style_name, span=1)

Starts a new table cell, using the paragraph style specified.

Parameters:

• style_name – TableCellStyle to use for the cell
• span – number of columns to span

start_link(link)

Start a link section. This defaults to underlining.

Parameters:link – should be an item that makes sense in this docgen type, if it implements linking.

start_paragraph(style_name, leader=None)

Starts a new paragraph, using the specified style name.

Parameters:

• style_name – name of the ParagraphStyle to use for the paragraph.
• leader – Leading text for a paragraph. Typically used for numbering.

start_row()

Starts a new row on the current table.

start_superscript()

start_table(name, style_name)

Starts a new table.

Parameters:

• name – Unique name of the table.
• style_name – TableStyle to use for the new table

start_underline()

Start a section of underlining. This passes without error so that docgen types are not required to have this.

stop_link()

Stop the link section. Defaults to stopping the underlining for docgen types that don’t support links.

stop_underline()

Stops a section of underlining. This passes without error so that docgen ntypes are not required to have this.

write_markup(text, s_tags, mark=None)

Writes the text in the current paragraph. Should only be used after a start_paragraph and before an end_paragraph. Not all backends support s_tags, then the same happens as with write_text. Backends supporting write_markup will overwrite this method

Parameters:

• text – text to write. The text is assumed to be _not_ escaped
• s_tags – assumed to be list of styledtexttags to apply to the text
• mark – IndexMark to use for indexing (if supported)

write_note(text, format, style_name)

Writes the note’s text and take care of paragraphs, depending on the format.

Parameters:

• text – text to write.
• format – format to use for writing. True for flowed text, 1 for preformatted text.

write_styled_note(styledtext, format, style_name, contains_html=False, links=False)

Convenience function to write a styledtext to the cairo doc.

Parameters:

• styledtext – assumed a StyledText object to write
• format – 0 = Flowed, 1 = Preformatted
• style_name – name of the style to use for default presentation
• contains_html – bool, the backend should not check if html is present. If contains_html=True, then the textdoc is free to handle that in some way. Eg, a textdoc could remove all tags, or could make sure a link is clickable.
• links – bool, make URLs in the text clickable (if supported)

overwrite this method if the backend supports styled notes

write_text(text, mark=None, links=False)

Writes the text in the current paragraph. Should only be used after a start_paragraph and before an end_paragraph.

Parameters:

• text – text to write.
• mark – IndexMark to use for indexing (if supported)
• links – make URLs in the text clickable (if supported)

write_text_citation(text, mark=None, links=None)

Method to write text with Gramps <super> citation marks.

Doc Backend

File and File format management for the different reports

class gramps.gen.plug.docbackend.cairobackend.CairoBackend(filename=None)

Bases: gramps.gen.plug.docbackend.docbackend.DocBackend

Implementation for cairo docs

ESCAPE_FUNC(x)

STYLETAG_MARKUP = {0: ('<b>', '</b>'), 1: ('<i>', '</i>'), 2: ('<u>', '</u>'), 7: ('^{', '}')}

STYLETAG_TO_PROPERTY = {3: 'face', 4: 'size', 5: 'foreground', 6: 'background'}

SUPPORTED_MARKUP = [0, 1, 2, 3, 4, 5, 6, 7]

File and File format management for the different reports

class gramps.gen.plug.docbackend.docbackend.DocBackend(filename=None)

Bases: object

Base class for text document backends. The DocBackend manages a file to which it writes. It further knowns enough of the file format to be able to translate between the BaseDoc API and the file format. Specifically for text reports a translation of styled notes to the file format usage is done.

BOLD = 0

CLASSMAP = None

ESCAPE_FUNC()

FONTCOLOR = 5

FONTFACE = 3

FONTSIZE = 4

HIGHLIGHT = 6

ITALIC = 1

LINK = 8

STYLETAG_MARKUP = {0: ('', ''), 1: ('', ''), 2: ('', ''), 8: ('', ''), 7: ('', '')}

STYLETYPE_MAP = {}

SUPERSCRIPT = 7

SUPPORTED_MARKUP = []

UNDERLINE = 2

add_markup_from_styled(text, s_tags, split='', escape=True)

Input is plain text, output is text with markup added according to the s_tags which are assumed to be styledtexttags. When split is given the text will be split over the value given, and tags applied in such a way that it the text can be safely splitted in pieces along split.

Parameters:

• text – str, a piece of text
• s_tags – styledtexttags that must be applied to the text
• split – str, optional. A string along which the output can be safely split without breaking the styling.

As adding markup means original text must be escaped, ESCAPE_FUNC is used. This can be used to convert the text of a styledtext to the format needed for a document backend. Do not call this method in a report, use the write_markup() method.

Note

the algorithm is complex as it assumes mixing of tags is not allowed: eg <b>text<i> here</b> not</i> is assumed invalid as markup. If the s_tags require such a setup, what is returned is <b>text</b><i><b> here</b> not</i> overwrite this method if this complexity is not needed.

close()

Closes the file that is written on.

escape(preformatted=False)

The escape func on text for this file format.

Parameters:preformatted (bool) – some formats can have different escape function for normal text and preformatted text

filename

The filename the backend works on

find_tag_by_stag(s_tag)

Parameters:

• s_tag – object: assumed styledtexttag
• s_tagvalue – None/int/str: value associated with the tag

A styled tag is type with a value. Every styled tag must be converted to the tags used in the corresponding markup for the backend, eg <b>text</b> for bold in html. These markups are stored in STYLETAG_MARKUP. They are tuples for begin and end tag. If a markup is not present yet, it is created, using the _create_xmltag() method you can overwrite.

format_link(value)

Default format for links. Override for better support.

value is: “TYPE DATA” where TYPE is ‘url’ or ‘ref’.

getf()

Obtain the filename on which backend writes

open()

Opens the document.

setf(value)

Set the filename on which the backend writes, changing the value passed on initialization. Can only be done if the previous filename is not open.

write(string)

Write a string to the file. There is no return value. Due to buffering, the string may not actually show up until the close() method is called.

writelines(sequence)

Write a sequence of strings to the file. The sequence can be any iterable object producing strings, typically a list of strings.

exception gramps.gen.plug.docbackend.docbackend.DocBackendError(value='')

Bases: exceptions.Exception

Error used to report docbackend errors.

gramps.gen.plug.docbackend.docbackend.noescape(text)

Function that does not escape the text passed. Default for backends

Register

This module provides the base class for plugin registration. It provides an object containing data about the plugin (version, filename, ...) and a register for the data of all plugins .

class gramps.gen.plug._pluginreg.PluginData

Bases: object

This is the base class for all plugin data objects. The workflow is:

1. plugin manager reads all register files, and stores plugin data objects in a plugin register
2. when plugin is needed, the plugin register creates the plugin, and the manager stores this, after which it can be executed.

Attributes present for all plugins

id

A unique identifier for the plugin. This is eg used to store the plugin

settings.

name

A friendly name to call this plugin (normally translated)

name_accell

A friendly name to call this plugin (normally translated), with an

accellerator present (eg '_Descendant report', with D to be accellerator

key

description

A friendly description of what the plugin does

version

The version of the plugin

status

The status of the plugin, STABLE or UNSTABLE

UNSTABLE is only visible in development code, not in release

fname

The python file where the plugin implementation can be found

fpath

The python path where the plugin implementation can be found

ptype

The plugin type. One of REPORT , QUICKREPORT, TOOL, IMPORT,

EXPORT, DOCGEN, GENERAL, MAPSERVICE, VIEW, GRAMPLET

authors

List of authors of the plugin, default=[]

authors_email

List of emails of the authors of the plugin, default=[]

supported

Bool value indicating if the plugin is still supported, default=True

load_on_reg

bool value, if True, the plugin is loaded on GRAMPS startup. Some

plugins. Only set this value if for testing you want the plugin to be

loaded immediately on startup. default=False

Attributes for RELCALC plugins:

relcalcclass

The class in the module that is the relationcalc class

lang_list

List of languages this plugin handles

Attributes for REPORT plugins:

require_active

Bool, If the reports requries an active person to be set or not

reportclass

The class in the module that is the report class

report_modes

The report modes: list of REPORT_MODE_GUI ,REPORT_MODE_BKI,REPORT_MODE_CLI

Attributes for REPORT and TOOL and QUICKREPORT and VIEW plugins

category

Or the report category the plugin belongs to, default=CATEGORY_TEXT

or the tool category a plugin belongs to, default=TOOL_UTILS

or the quickreport category a plugin belongs to, default=CATEGORY_QR_PERSON

or the view category a plugin belongs to,

default=("Miscellaneous", _("Miscellaneous"))

Attributes for REPORT and TOOL and DOCGEN plugins

optionclass

The class in the module that is the option class

Attributes for TOOL plugins

toolclass

The class in the module that is the tool class

tool_modes

The tool modes: list of TOOL_MODE_GUI, TOOL_MODE_CLI

Attributes for DOCGEN plugins

docclass

The class in the module that is the BaseDoc defined

paper

bool, Indicates whether the plugin uses paper or not, default=True

style

bool, Indicates whether the plugin uses styles or not, default=True

Attribute for DOCGEN, EXPORT plugins

extension

str, The file extension to use for output produced by the docgen/export,

default=''

Attributes for QUICKREPORT plugins

runfunc

The function that executes the quick report

Attributes for MAPSERVICE plugins

mapservice

The class in the module that is a mapservice

Attributes for EXPORT plugins

export_function

Function that produces the export

export_options

Class to set options

export_options_title

Title for the option page

Attributes for IMPORT plugins

import_function

Function that starts an import

Attributes for GRAMPLET plugins

gramplet

The function or class that defines the gramplet.

height

The height the gramplet should have in a column on GrampletView,

default = 200

detached_height

The height the gramplet should have detached, default 300

detached_width

The width the gramplet should have detached, default 400

expand

If the attributed should be expanded on start, default False

gramplet_title

Title to use for the gramplet, default = _('Gramplet')

navtypes

Navigation types that the gramplet is appropriate for, default = []

help_url

The URL where documentation for the URL can be found

Attributes for VIEW plugins

viewclass

A class of type ViewCreator that holds the needed info of the

view to be created: icon, viewclass that derives from pageview, ...

stock_icon

The icon in the toolbar or sidebar used to select the view

Attributes for SIDEBAR plugins

sidebarclass

The class that defines the sidebar.

menu_label

A label to use on the seltion menu.

Attributes for VIEW and SIDEBAR plugins

order

order can be START or END. Default is END. For END, on registering,

the plugin is appended to the list of plugins. If START, then the

plugin is prepended. Only set START if you want a plugin to be the

first in the order of plugins

authors

authors_email

category

data

depends_on

description

detached_height

detached_width

expand

export_function

export_options

export_options_title

extension

fname

fpath

gramplet

gramplet_title

gramps_target_version

height

help_url

icondir

icons

id

import_function

include_in_listing

lang_list

load_on_reg

mapservice

menu_label

name

name_accell

navtypes

optionclass

order

orientation

paper

process

ptype

relcalcclass

report_modes

reportclass

require_active

runfunc

sidebarclass

status

statustext()

stock_icon

style

supported

tool_modes

toolclass

version

viewclass

class gramps.gen.plug._pluginreg.PluginRegister

Bases: object

PluginRegister is a Singleton which holds plugin data

add_plugindata(plugindata)

bookitem_plugins()

Return a list of REPORT PluginData that are can be used as bookitem

docgen_plugins()

Return a list of PluginData that are of type DOCGEN

export_plugins()

Return a list of PluginData that are of type EXPORT

filter_load_on_reg()

Return a list of PluginData that have load_on_reg == True

general_plugins(category=None)

Return a list of PluginData that are of type GENERAL

static get_instance()

Use this function to get the instance of the PluginRegister

get_plugin(id)

Return the PluginData for the plugin with id

gramplet_plugins()

Return a list of PluginData that are of type GRAMPLET

import_plugins()

Return a list of PluginData that are of type IMPORT

mapservice_plugins()

Return a list of PluginData that are of type MAPSERVICE

quickreport_plugins()

Return a list of PluginData that are of type QUICKREPORT

relcalc_plugins()

Return a list of PluginData that are of type RELCALC

report_plugins(gui=True)

Return a list of gui or cli PluginData that are of type REPORT

Parameters:gui – bool, if True then gui plugin, otherwise cli plugin

scan_dir(dir)

The dir name will be scanned for plugin registration code, which will be loaded in PluginData objects if they satisfy some checks.

Returns:A list with PluginData objects

sidebar_plugins()

Return a list of PluginData that are of type SIDEBAR

tool_plugins(gui=True)

Return a list of PluginData that are of type TOOL

type_plugins(ptype)

Return a list of PluginData that are of type ptype

view_plugins()

Return a list of PluginData that are of type VIEW

gramps.gen.plug._pluginreg.make_environment(**kwargs)

gramps.gen.plug._pluginreg.myint(s)

Protected version of int()

gramps.gen.plug._pluginreg.newplugin()

Function to create a new plugindata object, add it to list of registered plugins

Returns:a newly created PluginData which is already part of the register

gramps.gen.plug._pluginreg.register(ptype, **kwargs)

Convenience function to register a new plugin using a dictionary as input. The register functions will call newplugin() function, and use the dictionary kwargs to assign data to the PluginData newplugin() created, as in: plugindata.key = data

Parameters:

• ptype – the plugin type, one of REPORT, TOOL, ...
• kwargs – dictionary with keys attributes of the plugin, and data the value

Returns:

a newly created PluginData which is already part of the register and which has kwargs assigned as attributes

gramps.gen.plug._pluginreg.valid_plugin_version(plugin_version_string)

Checks to see if string is a valid version string for this version of Gramps.

gramps.gen.plug._pluginreg.version(sversion)

Return the tuple version of a string version.

Utils

General utility functions useful for the generic plugin system

class gramps.gen.plug.utils.OpenFileOrStdin(filename, add_mode='')

Context manager to open a file or stdin for reading.

class gramps.gen.plug.utils.OpenFileOrStdout(filename)

Context manager to open a file or stdout for writing.

class gramps.gen.plug.utils.Zipfile(buffer)

Bases: object

Class to duplicate the methods of tarfile.TarFile, for Python 2.5.

close()

Close the zip object.

extractall(path, members=None)

Extract all of the files in the zip into path.

extractfile(name)

Extract a name from the zip file.

>>> Zipfile(buffer).extractfile("Dir/dile.py").read()
<Contents>

get_files(items)

Get the files from the items.

get_paths(items)

Get the directories from the items.

getnames()

Get the files and directories of the zipfile.

is_file(name)

Is the name a directory?

is_path(name)

Is the name a path?

gramps.gen.plug.utils.available_updates()

gramps.gen.plug.utils.load_addon_file(path, callback=None)

Load an addon from a particular path (from URL or file system).

class gramps.gen.plug.utils.newplugin

Bases: object

Fake newplugin.

gramps.gen.plug.utils.register(ptype, **kwargs)

Fake registration. Side-effect sets register_results to kwargs.

gramps.gen.plug.utils.version_str_to_tup(sversion, positions)

Given a string version and positions count, returns a tuple of integers.

>>> version_str_to_tup("1.02.9", 2)
(1, 2)