The cli Module

Package init for the cli package.

Argument Handler

Module responsible for handling the command line arguments for Gramps.

class gramps.cli.arghandler.ArgHandler(dbstate, parser, sessionmanager, errorfunc=None, gui=False)

Bases: object

This class is responsible for the non GUI handling of commands. The handler is passed a parser object, sanitizes it, and can execute the actions requested working on a DbState.

check_db(dbpath, force_unlock=False)

Test a given family tree path if it can be opened.

cl_action(action, options_str)

Command-line action routine. Try to perform specified action.

cl_export(filename, family_tree_format)

Command-line export routine. Try to write into filename using the family_tree_format.

cl_import(filename, family_tree_format)

Command-line import routine. Try to import filename using the family_tree_format.

cleanup()

clean up any remaining files

handle_args_cli(cleanup=True)

Depending on the given arguments, import or open data, launch session, write files, and/or perform actions.

Param:

climan: the manager of a CLI session

Type:

CLIManager object

handle_args_gui()

Method to handle the arguments that can be given for a GUI session.

Returns:

the filename of the family tree that should be opened if user just passed a famtree or a filename.

1. no options: a family tree can be given, if so, this name is tested and returned. If a filename, it is imported in a new db and name of new db returned

2. an open and/or import option can have been given, if so, this is handled, and None is returned

sanitize_args(importlist, exportlist)

Check the lists with open, exports, imports, and actions options.

Argument Parser

Module responsible for handling the command line arguments for Gramps.

class gramps.cli.argparser.ArgParser(args)

Bases: object

This class is responsible for parsing the command line arguments (if any) given to gramps, and determining if a GUI or a CLI session must be started. A filename and/or options may be specified as arguments.

The valid options are:

-O, --open=FAMILY_TREE

Open Family Tree

-U, --username=USERNAME

Database username

-P, --password=PASSWORD

Database password

-C, --create=FAMILY_TREE

Create on open if new Family Tree

-i, --import=FILENAME

Import file

-e, --export=FILENAME

Export file

-r, --remove=PATTERN

Remove matching Family Tree(s)

-f, --format=FORMAT

Specify Family Tree format

-a, --action=ACTION

Specify action

-p, --options=OPTIONS_STRING

Specify options

-d, --debug=LOGGER_NAME

Enable debug logs

-l [FAMILY_TREE…] List Family Trees -L [FAMILY_TREE…] List Family Trees in Detail -t [FAMILY_TREE…] List Family Trees, tab delimited -u, –force-unlock Force unlock of Family Tree -s, –show Show config settings -c, –config=SETTINGS Set config setting(s) and start Gramps -y, –yes Don’t ask to confirm dangerous actions -q, –quiet Suppress progress indication output -v, –version Show versions -h, –help Display the help –usage Display usage information

If the filename (no options) is specified, the interactive session is launched using data from filename. In this mode (filename, no options), the rest of the arguments are ignored. This is a mode suitable by default for GUI launchers, mime type handlers, and the like.

If no filename or -i option is given, a new interactive session (empty database) is launched, since no data is given anyway.

If -O or -i option is given, but no -e or -a options are given, an interactive session is launched with the FILENAME (specified with -i).

If both input (-O or -i) and processing (-e or -a) options are given, interactive session will not be launched.

When using import or export options (-i or -e), the -f option may be specified to indicate the family tree format.

Possible values for ACTION are: ‘report’, ‘book’ and ‘tool’.

Configuration SETTINGS may be specified using the -c option. The settings are of the form config.setting[:value]. If used without a value, the setting is shown.

If the -y option is given, the user’s acceptance of any CLI prompt is assumed. (see cli.user.User.prompt())

If the -q option is given, extra noise on sys.stderr, such as progress indicators, is suppressed.

need_gui()

Determine whether we need a GUI session for the given tasks.

parse_args()

Fill in lists with open, exports, imports, and actions options.

Any errors are added to self.errors

print_help()

If the user gives the –help or -h option, print the output to terminal.

print_usage()

If the user gives the –usage print the output to terminal.

CLI DB manager

Provide the management of databases from CLI. This includes opening, renaming, creating, and deleting of databases.

class gramps.cli.clidbman.CLIDbManager(dbstate)

Bases: object

Database manager without GTK functionality, allows users to create and open databases

ERROR(errormessage)

Show the error. A title for the error and an errormessage

ICON_LOCK = 2

ICON_MAP = {0: None, 1: None, 2: None, 3: None}

ICON_NONE = 0

ICON_OPEN = 3

ICON_RECOVERY = 1

IND_NAME = 0

IND_PATH = 1

IND_PATH_NAMEFILE = 2

IND_STOCK_ID = 6

IND_TVAL = 4

IND_TVAL_STR = 3

IND_USE_ICON_BOOL = 5

backend_unavailable(dbpath)

Returns True if the database in dirpath has an unavailable backend

break_lock(dbpath)

Breaks the lock on a database

create_new_db_cli(title=None, create_db=True, dbid=None)

Create a new database.

empty(val)

Callback that does nothing

family_tree_list()

Return a list of name, dirname of the known family trees

family_tree_summary(database_names=None)

Return a list of dictionaries of the known family trees.

get_backend_name_from_dbid(dbid)

get_dbdir_summary(dirpath, name)

dirpath: full path to database name: proper name of family tree

Returns dictionary of summary item. Should include at least, if possible:

_(“Path”) _(“Family Tree”) _(“Last accessed”) _(“Database”) _(“Locked?”)

and these details:

_(“Number of people”) _(“Version”) _(“Schema version”)

get_family_tree_path(name)

Given a name, return None if name not existing or the path to the database if it is a known database name.

icon_values(dirpath, active, is_open)

If the directory path is the active path, then return values that indicate to use the icon, and which icon to use.

import_new_db(filename, user)

Attempt to import the provided file into a new database. A new database will only be created if an appropriate importer was found.

Parameters:

• filename – a fully-qualified path, filename, and extension to open.

• user – a cli.user.User or gui.user.User instance for managing user interaction.

Returns:

A tuple of (new_path, name) for the new database or (None, None) if no import was performed.

is_locked(dbpath)

Returns True if there is a lock file in the dirpath

needs_recovery(dbpath)

Returns True if the database in dirpath needs recovery

print_family_tree_summaries(database_names=None)

Prints a detailed list of the known family trees.

remove_database(dbname, user=None)

Deletes a database folder given a pattenr that matches its proper name.

rename_database(filepath, new_text)

Renames the database by writing the new value to the name.txt file Returns old_name, new_name if success, None, None if no success

Gramps CLI

Provides the startcli function, which the main program calls for CLI execution of Gramps.

Provides also two small base classes: CLIDbLoader, CLIManager

class gramps.cli.grampscli.CLIDbLoader(dbstate)

Bases: object

Base class for Db loading action inside a DbState. Only the minimum is present needed for CLI handling

read_file(filename, username, password)

This method takes care of changing database, and loading the data. In 3.0 we only allow reading of real databases of filetype ‘x-directory/normal’

This method should only return on success. Returning on failure makes no sense, because we cannot recover, since database has already been changed. Therefore, any errors should raise exceptions.

On success, return with the disabled signals. The post-load routine should enable signals, as well as finish up with other UI goodies.

class gramps.cli.grampscli.CLIManager(dbstate, setloader, user)

Bases: object

Sessionmanager for Gramps. This is in effect a reduced ViewManager instance (see gui/viewmanager), suitable for CLI actions. Aim is to manage a dbstate on which to work (load, unload), and interact with the plugin session

do_reg_plugins(dbstate, uistate, rescan=False)

Register the plugins at initialization time.

open_activate(path, username=None, password=None)

Open and make a family tree active

User

The User class provides basic interaction with the user.

class gramps.cli.user.User(callback=None, error=None, auto_accept=False, quiet=False, uistate=None, dbstate=None)

Bases: UserBase

This class provides a means to interact with the user via CLI. It implements the interface in gen.user.UserBase

begin_progress(title, message, steps)

Start showing a progress indicator to the user.

Parameters:

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

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

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

Returns:

none

end_progress()

Stop showing the progress indicator to the user.

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

Displays information to the CLI

notify_db_error(error)

Notify the user of a DB error.

Parameters:

error (str) – the error message

Returns:

none

These exact strings are also in gui/dialog.py – keep them in sync

notify_db_repair(error)

Notify the user their DB might need repair.

Parameters:

error (str) – the error message

Returns:

none

These exact strings are also in gui/dialog.py – keep them in sync

notify_error(title, error='')

Notify the user of an error.

Parameters:

• title (str) – the title of the error

• error (str) – the error message

Returns:

none

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

Prompt the user with a message to select an alternative.

Parameters:

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

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

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

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

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

Returns:

the user’s answer to the question

Return type:

bool

step_progress()

Advance the progress meter.

warn(title, warning='')

Warn the user.

Parameters:

• title (str) – the title of the warning

• warning (str) – the warning

Returns:

none