Cyclone-Team/gramps
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Improve cli documentation

Browse Source
This commit is contained in:
Nick Hall 2013-11-13 01:18:00 +00:00
parent c4daa151a5
commit 55a3c9813f
5 changed files with 157 additions and 135 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

81
gramps/cli/arghandler.py
View File

@ -28,7 +28,7 @@
# $Id$ # $Id$
""" """
Module responsible for handling the command line arguments for GRAMPS. Module responsible for handling the command line arguments for Gramps.
""" """
#------------------------------------------------------------------------- #-------------------------------------------------------------------------
@ -67,24 +67,31 @@ def _split_options(options_str):
Split the options for the action. Split the options for the action.
Rules: Rules:
* Entries in the list of options are separated by commas without
spaces between entries * Entries in the list of options are separated by commas without
* List values must be inclosed in brackets ("[" and "]") spaces between entries
* Entries within a list value are separated by commas * List values must be inclosed in brackets ("[" and "]")
* Text values (as a value or as entries in a list) do not have to be * Entries within a list value are separated by commas
enclosed in quotes unless they include commas or quotation marks. * Text values (as a value or as entries in a list) do not have to be
* Text containing double quotes must be contained in single quotes enclosed in quotes unless they include commas or quotation marks.
* Text containing single quotes must be contained in double quotes * Text containing double quotes must be contained in single quotes
* Text cannot include both single and double quotes * Text containing single quotes must be contained in double quotes
* Text cannot include both single and double quotes
Examples: Examples:
* Multiple options specified:
report -p 'name=ancestor_chart,father_disp=["$n born $b"]' Multiple options specified::
* Using text with commas and quotes:
title="This is some text with ,s and 's" report -p 'name=ancestor_chart,father_disp=["$n born $b"]'
title='This is some text with ,s and "s'
* Using a list of text Using text with commas and quotes::
textlist=[row1,row2,"row3 with ' and ,"]
title="This is some text with ,s and 's"
title='This is some text with ,s and "s'
Using a list of text::
textlist=[row1,row2,"row3 with ' and ,"]
""" """
name = "" name = ""
value = "" value = ""
@ -147,7 +154,7 @@ class ArgHandler(object):
""" """
This class is responsible for the non GUI handling of commands. This class is responsible for the non GUI handling of commands.
The handler is passed a parser object, sanitizes it, and can execute the The handler is passed a parser object, sanitizes it, and can execute the
actions requested working on a DbState. actions requested working on a :class:`.DbState`.
""" """
def __init__(self, dbstate, parser, sessionmanager, def __init__(self, dbstate, parser, sessionmanager,
@ -269,8 +276,9 @@ class ArgHandler(object):
def __handle_export_option(self, value, family_tree_format): def __handle_export_option(self, value, family_tree_format):
""" """
Handle the "-e" or "--export" option. Handle the "-e" or "--export" option.
Note: this can only happen in the CLI version.
.. note:: this can only happen in the CLI version.
""" """
if self.gui: if self.gui:
return return
@ -317,8 +325,8 @@ class ArgHandler(object):
""" """
Attempt to find a database path for the given parameter. Attempt to find a database path for the given parameter.
@return: The path to a Gramps DB :returns: The path to a Gramps DB or None if a database can not be
or None if a database can not be deduced. deduced.
""" """
# First, check if this is the name of a family tree # First, check if this is the name of a family tree
db_path = self.dbman.get_family_tree_path(db_name_or_path) db_path = self.dbman.get_family_tree_path(db_name_or_path)
@ -341,15 +349,16 @@ class ArgHandler(object):
#------------------------------------------------------------------------- #-------------------------------------------------------------------------
def handle_args_gui(self): def handle_args_gui(self):
""" """
method to handle the arguments that can be given for a GUI session. 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 :returns: the filename of the family tree that should be opened if
1/no options: a family tree can be given, if so, this name is user just passed a famtree or a filename.
tested and returned. If a filename, it is imported
in a new db and name of new db returned 1. no options: a family tree can be given, if so, this name is tested
2/an open and/or import option can have been given, if so, this and returned. If a filename, it is imported in a new db and name of
is handled, and None is returned new db returned
2. an open and/or import option can have been given, if so, this is
handled, and None is returned
""" """
if self.open_gui: if self.open_gui:
# First check if a Gramps database was provided # First check if a Gramps database was provided
@ -387,8 +396,8 @@ class ArgHandler(object):
Depending on the given arguments, import or open data, launch Depending on the given arguments, import or open data, launch
session, write files, and/or perform actions. session, write files, and/or perform actions.
@param: climan: the manager of a CLI session :param: climan: the manager of a CLI session
@type: CLIManager object :type: :class:`.CLIManager` object
""" """
if self.list: if self.list:
@ -461,8 +470,10 @@ class ArgHandler(object):
def __import_action(self): def __import_action(self):
""" """
Take action for all given import files. Note: Family trees are Take action for all given import files.
not supported.
.. note:: Family trees are not supported.
If a family tree is open, the import happens on top of it. If not If a family tree is open, the import happens on top of it. If not
open, a new family tree is created, and the import done. If this open, a new family tree is created, and the import done. If this
is CLI, the created tree is deleted at the end (as some action will is CLI, the created tree is deleted at the end (as some action will

86
gramps/cli/argparser.py
View File

@ -28,7 +28,7 @@
# $Id$ # $Id$
""" """
Module responsible for handling the command line arguments for GRAMPS. Module responsible for handling the command line arguments for Gramps.
""" """
#------------------------------------------------------------------------- #-------------------------------------------------------------------------
@ -133,35 +133,58 @@ class ArgParser(object):
""" """
This class is responsible for parsing the command line arguments (if any) 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. given to gramps, and determining if a GUI or a CLI session must be started.
The valid arguments are: A filename and/or options may be specified as arguments.
Possible: The valid options are:
1/ FAMTREE : Just the family tree (name or database dir)
2/ -O, --open=FAMTREE, Open of a family tree -O, --open=FAMILY_TREE Open Family Tree
3/ -i, --import=FILE, Import a family tree of any format understood -C, --create=FAMILY_TREE Create on open if new Family Tree
by an importer, optionally provide -f to indicate format -i, --import=FILENAME Import file
4/ -e, --export=FILE, export a family tree in required format, -e, --export=FILENAME Export file
optionally provide -f to indicate format -f, --format=FORMAT Specify Family Tree format
5/ -f, --format=FORMAT : format after a -i or -e option -a, --action=ACTION Specify action
6/ -a, --action: An action (possible: 'report', 'tool') -p, --options=OPTIONS_STRING Specify options
7/ -p, --options=OPTIONS_STRING : specify options -d, --debug=LOGGER_NAME Enable debug logs
8/ -u, --force-unlock: A locked database can be unlocked by giving -l List Family Trees
this argument when opening it -L List Family Trees in Detail
-t List Family Trees, tab delimited
If the filename (no flags) is specified, the interactive session is -u, --force-unlock Force unlock of Family Tree
launched using data from filename. -s, --show Show config settings
In this mode (filename, no flags), the rest of the arguments is ignored. -c, --config=SETTINGS Set config setting(s) and start Gramps
This is a mode suitable by default for GUI launchers, mime type handlers, -y, --yes Don't ask to confirm dangerous actions
and the like -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 If no filename or -i option is given, a new interactive session (empty
database) is launched, since no data is given anyway. 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 If -O or -i option is given, but no -e or -a options are given, an
interactive session is launched with the FILE (specified with -i). interactive session is launched with the ``FILENAME`` (specified with -i).
If both input (-O or -i) and processing (-e or -a) options are given, If both input (-O or -i) and processing (-e or -a) options are given,
interactive session will not be launched. interactive session will not be launched.
When using import ot 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 :meth:`.cli.user.User.prompt`)
If the -q option is given, extra noise on sys.stderr, such as progress
indicators, is suppressed.
""" """
def __init__(self, args): def __init__(self, args):
@ -198,25 +221,6 @@ class ArgParser(object):
Fill in lists with open, exports, imports, and actions options. Fill in lists with open, exports, imports, and actions options.
Any errors are added to self.errors Any errors are added to self.errors
Possible:
1/ Just the family tree (name or database dir)
2/ -O --open: Open of a family tree
3/ -i --import: Import a family tree of any format understood by
an importer, optionally provide -f to indicate format
4/ -e --export: export a family tree in required format, optionally
provide -f to indicate format
5/ -f --format=FORMAT : format after a -i or -e option
6/ -a --action: An action (possible: 'report', 'tool')
7/ -p --options=OPTIONS_STRING : specify options
8/ -u --force-unlock: A locked database can be unlocked by giving
this argument when opening it
9/ -s --show : Show config settings
10/ -c --config=config.setting:value : Set config.setting and start
Gramps without :value, the actual config.setting is shown
11/ -y --yes: assume user's acceptance of any CLI prompt (see cli.user.User.prompt)
12/ -q --quiet: suppress extra noise on sys.stderr, such as progress indicators
""" """
try: try:
# Convert arguments to unicode, otherwise getopt will not work # Convert arguments to unicode, otherwise getopt will not work

25
gramps/cli/clidbman.py
View File

@ -134,7 +134,8 @@ class CLIDbManager(object):
self._populate_cli() self._populate_cli()
def empty(self, val): def empty(self, val):
"""Callback that does nothing """
Callback that does nothing
""" """
pass pass
@ -228,7 +229,8 @@ class CLIDbManager(object):
return summary_list return summary_list
def _populate_cli(self): def _populate_cli(self):
""" Get the list of current names in the database dir """
Get the list of current names in the database dir
""" """
# make the default directory if it does not exist # make the default directory if it does not exist
dbdir = os.path.expanduser(config.get('behavior.database-path')) dbdir = os.path.expanduser(config.get('behavior.database-path'))
@ -270,7 +272,8 @@ class CLIDbManager(object):
return None return None
def family_tree_list(self): def family_tree_list(self):
"""Return a list of name, dirname of the known family trees """
Return a list of name, dirname of the known family trees
""" """
lst = [(x[0], x[1]) for x in self.current_names] lst = [(x[0], x[1]) for x in self.current_names]
return lst return lst
@ -327,14 +330,14 @@ class CLIDbManager(object):
A new database will only be created if an appropriate importer was A new database will only be created if an appropriate importer was
found. found.
@param filename: a fully-qualified path, filename, and :param filename: a fully-qualified path, filename, and
extension to open. extension to open.
@param user: a cli.User or gui.User instance for managing user :param user: a :class:`.cli.user.User` or :class:`.gui.user.User`
interaction. instance for managing user interaction.
@return: A tuple of (new_path, name) for the new database :returns: A tuple of (new_path, name) for the new database
or (None, None) if no import was performed. or (None, None) if no import was performed.
""" """
pmgr = BasePluginManager.get_instance() pmgr = BasePluginManager.get_instance()
# check to see if it isn't a filename directly: # check to see if it isn't a filename directly:
@ -388,7 +391,7 @@ class CLIDbManager(object):
def is_locked(self, dbpath): def is_locked(self, dbpath):
""" """
returns True if there is a lock file in the dirpath Returns True if there is a lock file in the dirpath
""" """
if os.path.isfile(os.path.join(dbpath,"lock")): if os.path.isfile(os.path.join(dbpath,"lock")):
return True return True
@ -396,7 +399,7 @@ class CLIDbManager(object):
def needs_recovery(self, dbpath): def needs_recovery(self, dbpath):
""" """
returns True if the database in dirpath needs recovery Returns True if the database in dirpath needs recovery
""" """
if os.path.isfile(os.path.join(dbpath,"need_recover")): if os.path.isfile(os.path.join(dbpath,"need_recover")):
return True return True

25
gramps/cli/grampscli.py
View File

@ -23,9 +23,9 @@
""" """
Provides the startcli function, which the main program calls for CLI Provides the startcli function, which the main program calls for CLI
execution of GRAMPS. execution of Gramps.
Provides also two small base classes: CLIDbLoader, CLIManager Provides also two small base classes: :class:`CLIDbLoader`, :class:`CLIManager`
""" """
#------------------------------------------------------------------------- #-------------------------------------------------------------------------
@ -73,8 +73,8 @@ from gramps.gen.recentfiles import recent_files
#------------------------------------------------------------------------- #-------------------------------------------------------------------------
class CLIDbLoader(object): class CLIDbLoader(object):
""" """
Base class for Db loading action inside a dbstate. Only the minimum is Base class for Db loading action inside a :class:`.DbState`. Only the
present needed for CLI handling minimum is present needed for CLI handling
""" """
def __init__(self, dbstate): def __init__(self, dbstate):
self.dbstate = dbstate self.dbstate = dbstate
@ -96,9 +96,11 @@ class CLIDbLoader(object):
def _dberrordialog(self, msg): def _dberrordialog(self, msg):
""" """
Show a database error. Show a database error.
@param: msg : an error message
@type: string :param msg: an error message
@note: Inherit for GUI action :type msg : string
.. note:: Inherit for GUI action
""" """
self._errordialog( '', _("Low level database corruption detected") self._errordialog( '', _("Low level database corruption detected")
+ '\n' + + '\n' +
@ -208,7 +210,7 @@ class CLIDbLoader(object):
class CLIManager(object): class CLIManager(object):
""" """
Sessionmanager for GRAMPS. This is in effect a reduced viewmanager Sessionmanager for Gramps. This is in effect a reduced :class:`.ViewManager`
instance (see gui/viewmanager), suitable for CLI actions. instance (see gui/viewmanager), suitable for CLI actions.
Aim is to manage a dbstate on which to work (load, unload), and interact Aim is to manage a dbstate on which to work (load, unload), and interact
with the plugin session with the plugin session
@ -314,9 +316,10 @@ class CLIManager(object):
def startcli(errors, argparser): def startcli(errors, argparser):
""" """
Starts a cli session of GRAMPS. Starts a cli session of Gramps.
errors : errors already encountered
argparser : ArgParser instance :param errors: errors already encountered
:param argparser: :class:`.ArgParser` instance
""" """
if errors: if errors:
#already errors encountered. Show first one on terminal and exit #already errors encountered. Show first one on terminal and exit

75
gramps/cli/user.py
View File

@ -56,14 +56,14 @@ _SPINNER = ['|', '/', '-', '\\']
class User(user.User): class User(user.User):
""" """
This class provides a means to interact with the user via CLI. This class provides a means to interact with the user via CLI.
It implements the interface in gramps.gen.user.User() It implements the interface in :class:`.gen.user.User`
""" """
def __init__(self, callback=None, error=None, auto_accept=False, quiet=False): def __init__(self, callback=None, error=None, auto_accept=False, quiet=False):
""" """
Init. Init.
@param error: If given, notify_error delegates to this callback :param error: If given, notify_error delegates to this callback
@type error: function(title, error) :type error: function(title, error)
""" """
user.User.__init__(self, callback, error) user.User.__init__(self, callback, error)
self.steps = 0; self.steps = 0;
@ -83,15 +83,15 @@ class User(user.User):
""" """
Start showing a progress indicator to the user. Start showing a progress indicator to the user.
@param title: the title of the progress meter :param title: the title of the progress meter
@type title: str :type title: str
@param message: the message associated with the progress meter :param message: the message associated with the progress meter
@type message: str :type message: str
@param steps: the total number of steps for the progress meter. :param steps: the total number of steps for the progress meter.
a value of 0 indicates that the ending is unknown and the a value of 0 indicates that the ending is unknown and the
meter should just show activity. meter should just show activity.
@type steps: int :type steps: int
@returns: none :returns: none
""" """
self._fileout.write(message) self._fileout.write(message)
self.steps = steps self.steps = steps
@ -123,18 +123,19 @@ class User(user.User):
""" """
Prompt the user with a message to select an alternative. Prompt the user with a message to select an alternative.
@param title: the title of the question, e.g.: "Undo history warning" :param title: the title of the question, e.g.: "Undo history warning"
@type title: str :type title: str
@param message: the message, e.g.: "Proceeding with the tool will :param message: the message, e.g.: "Proceeding with the tool will erase
erase the undo history. If you think you may want to revert the undo history. If you think you may want to revert
running this tool, please stop here and make a backup of the DB." running this tool, please stop here and make a backup
@type question: str of the DB."
@param accept_label: what to call the positive choice, e.g.: "Proceed" :type question: str
@type accept_label: str :param accept_label: what to call the positive choice, e.g.: "Proceed"
@param reject_label: what to call the negative choice, e.g.: "Stop" :type accept_label: str
@type reject_label: str :param reject_label: what to call the negative choice, e.g.: "Stop"
@returns: the user's answer to the question :type reject_label: str
@rtype: bool :returns: the user's answer to the question
:rtype: bool
""" """
accept_label = accept_label.replace("_", "") accept_label = accept_label.replace("_", "")
reject_label = reject_label.replace("_", "") reject_label = reject_label.replace("_", "")
@ -154,11 +155,11 @@ class User(user.User):
""" """
Warn the user. Warn the user.
@param title: the title of the warning :param title: the title of the warning
@type title: str :type title: str
@param warning: the warning :param warning: the warning
@type warning: str :type warning: str
@returns: none :returns: none
""" """
self._fileout.write("%s %s" % (title, warning)) self._fileout.write("%s %s" % (title, warning))
@ -166,11 +167,11 @@ class User(user.User):
""" """
Notify the user of an error. Notify the user of an error.
@param title: the title of the error :param title: the title of the error
@type title: str :type title: str
@param error: the error message :param error: the error message
@type error: str :type error: str
@returns: none :returns: none
""" """
if self.error_function: if self.error_function:
self.error_function(title, error) self.error_function(title, error)
@ -181,9 +182,9 @@ class User(user.User):
""" """
Notify the user of a DB error. Notify the user of a DB error.
@param error: the error message :param error: the error message
@type error: str :type error: str
@returns: none :returns: none
""" """
self.notify_error( self.notify_error(
_("Low level database corruption detected"), _("Low level database corruption detected"),