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.

@return: a string that describes the plugin

get_module_name()

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

@return: a string representing the name of the module for this plugin

get_name()

Get the name of this plugin.

@return: 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.

@return: a list of DocGenPlugin names

get_docgen_plugins()

Get the list of docgen plugins.

@return: [gen.plug.DocGenPlugin] (a list of DocGenPlugin instances)

get_export_plugins()

Get the list of export plugins.

@return: [gen.plug.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.

@return: [gen.plug.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 :Param 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. @param option: the option class @type option: class that inherits from gen.plug.menu.Option @param guioption: the gui-option class @type guioption: class that inherits from Gtk.Widget.

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.

@return: (??,??)

get_export_function()

Get the export function for this plugin.

@return: the callable export_function passed into __init__

get_extension()

Get the file extension for the export file.

@return: 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:

‘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.

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:

‘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.

@return: str

get_import_function()

Get the import function for this plugins.

@return: the callable import_function passed into __init__

Menu

Abstracted option handling.

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

Bases: object

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.

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.

@param category: A label that describes the category that the option
belongs to. Example: “Report Options”

@type category: string @param name: A name that is unique to this option.

Example: “generations”

@type name: string @param option: The option instance to be added to this menu. @type option: gen.plug.menu.Option @return: nothing

get_all_option_names()

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

@return: a list of strings

get_categories()

Get a list of categories in this menu.

@return: a list of strings

get_option(category, name)

Get an option with the specified category and name.

@return: an Option instance or None on failure.

get_option_by_name(name)

Get an option with the specified name.

@return: an Option instance or None on failure.

get_option_names(category)

Get a list of option names for the specified category.

@return: 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.

@param description: A description for this check button.
Example: “Census”

@type description: string @param value: The default for this check button (True or False).

Example: True

@type value: int @return: nothing

get_descriptions()

Get a list of check button descriptions for this option.

@return: a list of check button descriptions.

get_selected()

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

@return: 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()

@return: True if the destination is a directory. False if the destination is a file.

get_extension()

@return: The extension for the destination file.

set_directory_entry(is_directory)

@param is_directory: Specifies whether the destination is a directory or a file. @type value: bool @return: nothing

set_extension(extension)

@param extension: Specifies the extension for the destination file. @type value: str @return: 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.

@param value: The value that corresponds to this item.
Example: 5

@type value: int @param description: A description of this value.

Example: “8.5 x 11”

@type description: string @return: nothing

clear()

Clear all possible values from this option.

@return: nothing.

get_items()

Get all the possible values for this option.

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

set_items(items)

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

@param items: A list of tuples containing value, description pairs.
Example: [ (5,”8.5 x 11”), (6,”11 x 17”)]

@type items: array @return: nothing

set_value(value)

Set the value of this option.

@param value: A value for this option.
Example: True

@type value: The type will depend on the type of option. @return: 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.

@return: A filter object.

set_filters(filter_list)

Set the list of filters available to be chosen from.

@param filter_list: An array of person filters. @type filter_list: array @return: 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.

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

get_min()

Get the minimum value for this option.

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

get_step()

Get the step size for this option.

@return: 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.

@return: 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.

@return: A string that provides additional help beyond the label.

get_label()

Get the friendly label for this option.

@return: string

get_value()

Get the value of this option.

@return: The option value.

set_available(avail)

Set the availability of this option.

@param avail: An indicator of whether this option is currently available. True indicates that the option is available. False indicates that the option is not available. @type avail: Bool @return: nothing

set_help(help_text)

Set the help information for this option.

@param 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”

@type value: string @return: nothing

set_label(label)

Set the friendly label for this option.

@param label: A friendly label to be applied to this option.
Example: “Exclude living people”

@type label: string @return: nothing

set_value(value)

Set the value of this option.

@param value: A value for this option.
Example: True

@type value: The type will depend on the type of option. @return: 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

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.

@param menu: A menu class for the options to belong to. @type menu: Menu @return: 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. @param name: name of the option to retrieve @type name: str @returns: value associated with the passed option @rtype: str

get_options()

Return the whole bunch of options for the OptionList. @returns: list of options @rtype: list

remove_option(name)

Remove a particular option from the OptionList. @param name: name of the option to remove. @type name: str

set_option(name, value)

Set a particular option in the OptionList. @param name: name of the option to set. @type name: str @param value: value of the option to set. @type str

set_options(options)

Set the whole bunch of options for the OptionList. @param options: list of options to set. @type options: list

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 @rtype: list

get_option_list(name)

Return the option_list associated with the module name @param name: name associated with the desired module. @type name: str @returns: returns the option list associated with the name,

or None of no such option exists

@rtype: str

get_option_list_map()

Return the map of module names to option lists. @returns: Returns the map of module names to option lists. @rtype: 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. @param name: name associated with the module to add or replace. @type name: str @param option_list: list of options @type option_list: OptionList

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 @rtype: str

get_custom_paper_size()

Return the custom paper size for the OptionList. @returns: returns the custom paper size in cm @rtype: [float, float]

get_format_name()

Return the format name of the OptionList. @returns: returns the format name @rtype: str

get_margin(pos)

Return a margin for the OptionList. @param pos: Position of margin [left, right, top, bottom] @type pos: int @returns: float cm of margin @rtype: 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

@rtype: int

get_output()

Return the output of the OptionList. @returns: returns the output name @rtype: str

get_paper_metric()

Return the paper metric of the OptionList. @returns: returns whether to use metric @rtype: boolean

get_paper_name()

Return the paper name of the OptionList. @returns: returns the paper name @rtype: str

get_style_name()

Return the style name of the OptionList. @returns: string representing the style name @rtype: str

set_css_filename(css_filename)

Set the template name for the OptionList. @param template_name: name of the template to set. @type template_name: str

set_custom_paper_size(paper_size)

Set the custom paper size for the OptionList. @param paper_size: paper size to set in cm. @type paper_size: [float, float]

set_format_name(format_name)

Set the format name for the OptionList. @param format_name: name of the format to set. @type format_name: str

set_margin(pos, value)

Set a margin for the OptionList. @param pos: Position of margin [left, right, top, bottom] @param value: floating point in cm @type pos: int @type value: float

set_margins(margins)

Set the margins for the OptionList. @param margins: margins to set. Possible values are floats in cm @type margins: [float, float, float, float]

set_orientation(orientation)

Set the orientation for the OptionList. @param orientation: orientation to set. Possible values are

PAPER_LANDSCAPE or PAPER_PORTRAIT

@type orientation: int

set_output(output)

Set the output for the OptionList. @param output: name of the output to set. @type output: str

set_paper_metric(paper_metric)

Set the paper metric for the OptionList. @param paper_metric: whether to use metric. @type paper_name: boolean

set_paper_name(paper_name)

Set the paper name for the OptionList. @param paper_name: name of the paper to set. @type paper_name: str

set_style_name(style_name)

Set the style name for the OptionList. @param style_name: name of the style to set. @type style_name: str

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) @rtype: [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. @param pos: position in margins list @type pos: int @returns: last margin used in pos @rtype: 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) @rtype: [float, float, float, float]

get_last_orientation()

Return the last orientation used for any report in this collection. @returns: last orientation used @rtype: 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 @rtype: boolean

get_last_paper_name()

Return the last paper name used for any report in this collection. @returns: returns the name of the paper @rtype: 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.

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. @param custom_paper_size: size to set in cm (width, height) @type custom_paper_size: [float, float]

set_last_format_name(format_name)

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

format_name: name of the format to set.

set_last_margin(pos, value)

Set the last margin used for any report in this collection. @param pos: pos to set (0-4) (left, right, top, bottom) @type pos: int @param value: value to set the margin to in cm @type value: float

set_last_margins(margins)

Set the last margins used for any report in this collection. @param margins: margins to set in cm (left, right, top, bottom) @type margins: [float, float, float, float]

set_last_orientation(orientation)

Set the last orientation used for any report in this collection. @param orientation: orientation to set. @type orientation: int

set_last_paper_metric(paper_metric)

Set the last paper metric used for any report in this collection. @param paper_metric: whether to use metric. @type paper_name: boolean

set_last_paper_name(paper_name)

Set the last paper name used for any report in this collection. @param paper_name: name of the paper to set. @type paper_name: str

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.

This method MUST NOT be overridden by subclasses.

get_output()

Return document output destination.

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:

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.

This method MUST NOT be overridden by subclasses.

set_output(val)

Set output destination to a given string.

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.

@param citation: Citation object @type citation: L{gen.lib.Citation} @return: 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. @rtype: (int,char) or (int,None)

N.B. 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.

@return: number of citations @rtype: int

get_citation_list()

Return a list containing all the citations in this bibliography.

@return: citation list @rtype: list of L{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.

@param source_ref: Source Reference @type source_ref: L{gen.lib.citation} @return: The key of the added reference among all the references. @rtype: char

get_ref_list()

List all the references to this citation.

@return: a list of references @rtype: list of L{gen.lib.srcref} objects

get_source_handle()

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

@return: Source Handle @rtype: handle

set_source_handle(handle)

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

@param handle: Source Handle @type handle: 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.

@param style_sheet: Style sheet @type style_sheet: L{docgen.StyleSheet}

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

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

@param bibliography: The bibliography to contain the citations. @type bibliography: L{Bibliography} @param obj: An object with source references. @type obj: L{gen.lib.CitationBase}

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

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.

@param bibliography: The bibliography that contains the citations. @type bibliography: L{Bibliography} @param database: The database that the sources come from. @type database: DbBase @param doc: The document to write the endnotes into. @type doc: L{docgen.TextDoc} @param printnotes: Indicate if the notes attached to a source must be

written too.

@type printnotes: bool @param links: Indicate if URL links should be makde ‘clickable’. @type links: bool @param elocale: allow deferred translation of dates and strings @type elocale: a GrampsLocale instance

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.

@param cm: centimeters @type cm: float or int @returns: equivalent units in points @rtype: 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

@param 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

@param person: the person the filters should apply to. @type person: L{Person} @param include_single: include a filter to include the single person @type person: boolean

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

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

@param db: the GRAMPS database instance @param 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.

@param pt: points @type pt: float or int @returns: equivalent units in centimeters @rtype: float

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

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

@param color: list or tuple of integer values for red, green, and blue @type color: int @returns: (r, g, b) tuple of floating point color values @rtype: 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.

@return: the BaseDoc class passed into __init__

get_basedocname()

Get the BaseDoc name for this plugin.

@return: the BaseDoc name passed into __init__

get_doc_option_class()

Get the DocOptions subclass for this plugin, if any

@return: the DocOptions subclass passed into __init__

get_draw_support()

Check if the plugin supports the DrawDoc interface.

@return: bool: True if DrawDoc is supported; False if DrawDoc is not
supported.
get_extension()

Get the file extension for the output file.

@return: str

get_paper_used()

Get the paper flag for this plugin.

@return: bool - True = use paper; False = do not use paper

get_style_support()

Get the style flag for this plugin.

@return: bool - True = use styles; False = do not use styles

get_text_support()

Check if the plugin supports the TextDoc interface.

@return: 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.

@param 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.

@param style_sheet: The new style sheet for the document @type style_sheet: StyleSheet

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)

@param mark: IndexMark to use for indexing (if supported)

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

@param 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)

@param 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)

@param 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.

@param face: font type face, either FONT_SERIF or FONT_SANS_SERIF @param size: type face size in points @param italic: True enables italics, False disables italics @param bold: True enables bold face, False disables bold face @param underline: True enables underline, False disables underline @param 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.

@param comment: A text string to add as a comment.
Example: “Next comes the individuals.”

@type comment: string @return: nothing

Add a link between two nodes.

@param id1: The unique identifier of the starting node.
Example: “p55”

@type id1: string @param id2: The unique identifier of the ending node.

Example: “p55”

@type id2: string @param comment: A text string displayed at the end of the link line.

Example: “person C is the son of person A and person B”

@type comment: string @return: 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.

@param node_id: A unique identification value for this node.
Example: “p55”

@type node_id: string @param label: The text to be displayed in the node.

Example: “John Smith”

@type label: string @param shape: The shape for the node.

Examples: “box”, “ellipse”, “circle”

@type shape: string @param color: The color of the node line.

Examples: “blue”, “lightyellow”

@type color: string @param style: The style of the node. @type style: string @param fillcolor: The fill color for the node.

Examples: “blue”, “lightyellow”

@type fillcolor: string @param url: A URL for the node. @type url: string @param htmloutput: Whether the label contains HTML. @type htmloutput: boolean @return: nothing

end_subgraph()

End a subgraph that was previously started in this graph.

@return: nothing

start_subgraph(graph_id)

Start a subgraph in this graph.

@param id: The unique identifier of the subgraph.
Example: “p55”

@type id1: string @return: 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 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.

@param menu: The menu the options should be added to. @type menu: gen.plug.menu.Menu() @return: 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 @rtype: float

get_left_margin()

Return the left margin.

@returns: Left margin in centimeters @rtype: float

get_orientation()

Return the orientation of the page.

@returns: PAPER_PORTRIAT or PAPER_LANDSCAPE @rtype: int

get_right_margin()

Return the right margin.

@returns: Right margin in centimeters @rtype: float

get_size()

Return the size of the paper.

@returns: object indicating the paper size @rtype: PaperSize

get_top_margin()

Return the top margin.

@returns: Top margin in centimeters @rtype: 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.

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

set_alignment(align)

Set the paragraph alignment.

@param 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.

@param 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.

@param 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.

@param 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.

@param 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

@param val: floating point value indicating the padding in centimeters

set_right_border(val)

Set the presence or absence of rigth border.

@param 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.

@param 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.

@param name: The name of the TableCellStyle @param style: TableCellStyle instance to be added.

add_draw_style(name, style)

Add a draw style to the style sheet.

@param name: The name of the GraphicsStyle @param style: GraphicsStyle instance to be added.

add_paragraph_style(name, style)

Add a paragraph style to the style sheet.

@param name: The name of the ParagraphStyle @param style: ParagraphStyle instance to be added.

add_table_style(name, style)

Add a table style to the style sheet.

@param name: The name of the TableStyle @param style: TableStyle instance to be added.

clear()

Remove all styles from the StyleSheet

get_cell_style(name)

Return the TableCellStyle associated with the name

@param 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

@param 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

@param 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

@param 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

@param 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

@param val: if True, a border is used, if False, it is not

set_bottom_border(val)

Defines if a bottom border in used

@param val: if 1, a bottom border is used, if 0, it is not

set_left_border(val)

Defines if a left border in used

@param 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

@param val: if True, a right border is used, if False, it is not

set_top_border(val)

Defines if a top border in used

@param 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.

@param 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.

@param index: column being set (index starts at 0) @param 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.

@param 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).

@param name: filename of the image to add @param align: alignment of the image. Valid values are ‘left’,

‘right’, ‘center’, and ‘single’

@param w_cm: width in centimeters @param h_cm: height in centimeters @param alt: an alternative text to use. Useful for eg html reports @param style_name: style to use for captions @param 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.

@param style_name: TableCellStyle to use for the cell @param span: number of columns to span

Start a link section. This defaults to underlining. @param 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.

@param style_name: name of the ParagraphStyle to use for the
paragraph.
@param 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.

@param name: Unique name of the table. @param 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 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

@param text: text to write. The text is assumed to be _not_ escaped @param s_tags: assumed to be list of styledtexttags to apply to the

text

@param 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.

@param text: text to write. @param 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. 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.

@param text: text to write. @param mark: IndexMark to use for indexing (if supported) @param 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: ('<sup>', '</sup>')}
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(x)
FONTCOLOR = 5
FONTFACE = 3
FONTSIZE = 4
HIGHLIGHT = 6
ITALIC = 1
STYLETAG_MARKUP = {0: ('', ''), 1: ('', ''), 2: ('', ''), 8: ('', ''), 7: ('', '')}
STYLETYPE_MAP = {}
SUPERSCRIPT = 7
SUPPORTED_MARKUP = []
UNDERLINE = 2
add_markup_from_styled(text, s_tags, split='')

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

@param text : str, a piece of text @param s_tags : styledtexttags that must be applied to the text @param 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. @param 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)

@param s_tag: object: assumed styledtexttag @param 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

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 untill 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
  1. 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 .. attribute:: 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: .. attribute:: relcalcclass

The class in the module that is the relationcalc class
lang_list
List of languages this plugin handles

Attributes for REPORT plugins: .. attribute:: 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 .. attribute:: 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 .. attribute:: optionclass

The class in the module that is the option class

Attributes for TOOL plugins .. attribute:: 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 .. attribute :: 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 .. attribute :: extension

str, The file extension to use for output produced by the docgen/export, default=’‘

Attributes for QUICKREPORT plugins .. attribute:: runfunc

The function that executes the quick report

Attributes for MAPSERVICE plugins .. attribute:: mapservice

The class in the module that is a mapservice

Attributes for EXPORT plugins .. attribute:: 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 .. attribute:: import_function

Function that starts an import

Attributes for GRAMPLET plugins .. attribute:: 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 .. attribute:: 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 .. attribute:: sidebarclass

The class that defines the sidebar.
menu_label
A label to use on the seltion menu.

Attributes for VIEW and SIDEBAR plugins .. attribute:: 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 .. attribute : stable_only

Bool, include stable plugins only or not. Default True
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 :param 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 :param ptype: the plugin type, one of REPORT, TOOL, ... :param 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)

Table Of Contents

Previous topic

The gramps.gen.display Module

Next topic

The gramps.gen.proxy Module

This Page