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$
"""
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.
Rules:
* Entries in the list of options are separated by commas without
spaces between entries
* List values must be inclosed in brackets ("[" and "]")
* Entries within a list value are separated by commas
* Text values (as a value or as entries in a list) do not have to be
enclosed in quotes unless they include commas or quotation marks.
* Text containing double quotes must be contained in single quotes
* Text containing single quotes must be contained in double quotes
* Text cannot include both single and double quotes
* Entries in the list of options are separated by commas without
spaces between entries
* List values must be inclosed in brackets ("[" and "]")
* Entries within a list value are separated by commas
* Text values (as a value or as entries in a list) do not have to be
enclosed in quotes unless they include commas or quotation marks.
* Text containing double quotes must be contained in single quotes
* Text containing single quotes must be contained in double quotes
* Text cannot include both single and double quotes
Examples:
* Multiple options specified:
report -p 'name=ancestor_chart,father_disp=["$n born $b"]'
* Using text with commas and quotes:
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 ,"]
Multiple options specified::
report -p 'name=ancestor_chart,father_disp=["$n born $b"]'
Using text with commas and quotes::
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 = ""
value = ""
@ -147,7 +154,7 @@ class ArgHandler(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.
actions requested working on a :class:`.DbState`.
"""
def __init__(self, dbstate, parser, sessionmanager,
@ -269,8 +276,9 @@ class ArgHandler(object):
def __handle_export_option(self, value, family_tree_format):
"""
Handle the "-e" or "--export" option.
Note: this can only happen in the CLI version.
Handle the "-e" or "--export" option.
.. note:: this can only happen in the CLI version.
"""
if self.gui:
return
@ -317,8 +325,8 @@ class ArgHandler(object):
"""
Attempt to find a database path for the given parameter.
@return: The path to a Gramps DB
or None if a database can not be deduced.
:returns: The path to a Gramps DB or None if a database can not be
deduced.
"""
# First, check if this is the name of a family tree
db_path = self.dbman.get_family_tree_path(db_name_or_path)
@ -341,15 +349,16 @@ class ArgHandler(object):
#-------------------------------------------------------------------------
def handle_args_gui(self):
"""
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
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
"""
if self.open_gui:
# 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
session, write files, and/or perform actions.
@param: climan: the manager of a CLI session
@type: CLIManager object
:param: climan: the manager of a CLI session
:type: :class:`.CLIManager` object
"""
if self.list:
@ -461,8 +470,10 @@ class ArgHandler(object):
def __import_action(self):
"""
Take action for all given import files. Note: Family trees are
not supported.
Take action for all given import files.
.. note:: Family trees are not supported.
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
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$
"""
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)
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:
1/ FAMTREE : Just the family tree (name or database dir)
2/ -O, --open=FAMTREE, Open of a family tree
3/ -i, --import=FILE, Import a family tree of any format understood
by an importer, optionally provide -f to indicate format
4/ -e, --export=FILE, 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
If the filename (no flags) is specified, the interactive session is
launched using data from filename.
In this mode (filename, no flags), the rest of the arguments is ignored.
This is a mode suitable by default for GUI launchers, mime type handlers,
and the like
The valid options are:
-O, --open=FAMILY_TREE Open Family Tree
-C, --create=FAMILY_TREE Create on open if new Family Tree
-i, --import=FILENAME Import file
-e, --export=FILENAME Export file
-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 List Family Trees
-L List Family Trees in Detail
-t 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 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,
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):
@ -198,25 +221,6 @@ class ArgParser(object):
Fill in lists with open, exports, imports, and actions options.
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:
# 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()
def empty(self, val):
"""Callback that does nothing
"""
Callback that does nothing
"""
pass
@ -228,7 +229,8 @@ class CLIDbManager(object):
return summary_list
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
dbdir = os.path.expanduser(config.get('behavior.database-path'))
@ -270,7 +272,8 @@ class CLIDbManager(object):
return None
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]
return lst
@ -327,14 +330,14 @@ class CLIDbManager(object):
A new database will only be created if an appropriate importer was
found.
@param filename: a fully-qualified path, filename, and
extension to open.
:param filename: a fully-qualified path, filename, and
extension to open.
@param user: a cli.User or gui.User instance for managing user
interaction.
:param user: a :class:`.cli.user.User` or :class:`.gui.user.User`
instance for managing user interaction.
@return: A tuple of (new_path, name) for the new database
or (None, None) if no import was performed.
:returns: A tuple of (new_path, name) for the new database
or (None, None) if no import was performed.
"""
pmgr = BasePluginManager.get_instance()
# check to see if it isn't a filename directly:
@ -388,7 +391,7 @@ class CLIDbManager(object):
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")):
return True
@ -396,7 +399,7 @@ class CLIDbManager(object):
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")):
return True

25
gramps/cli/grampscli.py
View File

@ -23,9 +23,9 @@
"""
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):
"""
Base class for Db loading action inside a dbstate. Only the minimum is
present needed for CLI handling
Base class for Db loading action inside a :class:`.DbState`. Only the
minimum is present needed for CLI handling
"""
def __init__(self, dbstate):
self.dbstate = dbstate
@ -96,9 +96,11 @@ class CLIDbLoader(object):
def _dberrordialog(self, msg):
"""
Show a database error.
@param: msg : an error message
@type: string
@note: Inherit for GUI action
:param msg: an error message
:type msg : string
.. note:: Inherit for GUI action
"""
self._errordialog( '', _("Low level database corruption detected")
+ '\n' +
@ -208,7 +210,7 @@ class CLIDbLoader(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.
Aim is to manage a dbstate on which to work (load, unload), and interact
with the plugin session
@ -314,9 +316,10 @@ class CLIManager(object):
def startcli(errors, argparser):
"""
Starts a cli session of GRAMPS.
errors : errors already encountered
argparser : ArgParser instance
Starts a cli session of Gramps.
:param errors: errors already encountered
:param argparser: :class:`.ArgParser` instance
"""
if errors:
#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):
"""
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):
"""
Init.
@param error: If given, notify_error delegates to this callback
@type error: function(title, error)
:param error: If given, notify_error delegates to this callback
:type error: function(title, error)
"""
user.User.__init__(self, callback, error)
self.steps = 0;
@ -83,15 +83,15 @@ class User(user.User):
"""
Start showing a progress indicator to the user.
@param title: the title of the progress meter
@type title: str
@param message: the message associated with the progress meter
@type message: str
@param steps: 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.
@type steps: int
@returns: none
:param title: the title of the progress meter
:type title: str
:param message: the message associated with the progress meter
:type message: str
:param steps: 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.
:type steps: int
:returns: none
"""
self._fileout.write(message)
self.steps = steps
@ -123,18 +123,19 @@ class User(user.User):
"""
Prompt the user with a message to select an alternative.
@param title: the title of the question, e.g.: "Undo history warning"
@type title: str
@param 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."
@type question: str
@param accept_label: what to call the positive choice, e.g.: "Proceed"
@type accept_label: str
@param reject_label: what to call the negative choice, e.g.: "Stop"
@type reject_label: str
@returns: the user's answer to the question
@rtype: bool
:param title: the title of the question, e.g.: "Undo history warning"
:type title: str
:param 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."
:type question: str
:param accept_label: what to call the positive choice, e.g.: "Proceed"
:type accept_label: str
:param reject_label: what to call the negative choice, e.g.: "Stop"
:type reject_label: str
:returns: the user's answer to the question
:rtype: bool
"""
accept_label = accept_label.replace("_", "")
reject_label = reject_label.replace("_", "")
@ -154,11 +155,11 @@ class User(user.User):
"""
Warn the user.
@param title: the title of the warning
@type title: str
@param warning: the warning
@type warning: str
@returns: none
:param title: the title of the warning
:type title: str
:param warning: the warning
:type warning: str
:returns: none
"""
self._fileout.write("%s %s" % (title, warning))
@ -166,11 +167,11 @@ class User(user.User):
"""
Notify the user of an error.
@param title: the title of the error
@type title: str
@param error: the error message
@type error: str
@returns: none
:param title: the title of the error
:type title: str
:param error: the error message
:type error: str
:returns: none
"""
if self.error_function:
self.error_function(title, error)
@ -181,9 +182,9 @@ class User(user.User):
"""
Notify the user of a DB error.
@param error: the error message
@type error: str
@returns: none
:param error: the error message
:type error: str
:returns: none
"""
self.notify_error(
_("Low level database corruption detected"),