mirror of https://github.com/borgbackup/borg.git
refactor CommonOptions as a reusable class
This commit is contained in:
Marian Beermann
parent
2ab5df0217
commit
b9efdb2ce3
|
|
@ -1870,6 +1870,126 @@ class Archiver:
|
|||
print(warning, file=sys.stderr)
|
||||
return args
|
||||
|
||||
class CommonOptions:
|
||||
"""
|
||||
Support class to allow specifying common options directly after the top-level command.
|
||||
|
||||
Normally options can only be specified on the parser defining them, which means
|
||||
that generally speaking *all* options go after all sub-commands. This is annoying
|
||||
for common options in scripts, e.g. --remote-path or logging options.
|
||||
|
||||
This class allows adding the same set of options to both the top-level parser
|
||||
and the final sub-command parsers (but not intermediary sub-commands, at least for now).
|
||||
|
||||
It does so by giving every option's target name ("dest") a suffix indicating its level
|
||||
-- no two options in the parser hierarchy can have the same target --
|
||||
then, after parsing the command line, multiple definitions are resolved.
|
||||
|
||||
Defaults are handled by only setting them on the top-level parser and setting
|
||||
a sentinel object in all sub-parsers, which then allows to discern which parser
|
||||
supplied the option.
|
||||
"""
|
||||
|
||||
def __init__(self, define_common_options, suffix_precedence):
|
||||
"""
|
||||
*define_common_options* should be a callable taking one argument, which
|
||||
will be a argparse.Parser.add_argument-like function.
|
||||
|
||||
*define_common_options* will be called multiple times, and should call
|
||||
the passed function to define common options exactly the same way each time.
|
||||
|
||||
*suffix_precedence* should be a tuple of the suffixes that will be used.
|
||||
It is ordered from lowest precedence to highest precedence:
|
||||
An option specified on the parser belonging to index 0 is overridden if the
|
||||
same option is specified on any parser with a higher index.
|
||||
"""
|
||||
self.define_common_options = define_common_options
|
||||
self.suffix_precedence = suffix_precedence
|
||||
|
||||
# Maps suffixes to sets of target names.
|
||||
# E.g. common_options["_subcommand"] = {..., "log_level", ...}
|
||||
self.common_options = dict()
|
||||
# Set of options with the 'append' action.
|
||||
self.append_options = set()
|
||||
# This is the sentinel object that replaces all default values in parsers
|
||||
# below the top-level parser.
|
||||
self.default_sentinel = object()
|
||||
|
||||
def add_common_group(self, parser, suffix, provide_defaults=False):
|
||||
"""
|
||||
Add common options to *parser*.
|
||||
|
||||
*provide_defaults* must only be True exactly once in a parser hierarchy,
|
||||
at the top level, and False on all lower levels. The default is chosen
|
||||
accordingly.
|
||||
|
||||
*suffix* indicates the suffix to use internally. It also indicates
|
||||
which precedence the *parser* has for common options. See *suffix_precedence*
|
||||
of __init__.
|
||||
"""
|
||||
assert suffix in self.suffix_precedence
|
||||
|
||||
def add_argument(*args, **kwargs):
|
||||
if 'dest' in kwargs:
|
||||
kwargs.setdefault('action', 'store')
|
||||
assert kwargs['action'] in ('help', 'store_const', 'store_true', 'store_false', 'store', 'append')
|
||||
is_append = kwargs['action'] == 'append'
|
||||
if is_append:
|
||||
self.append_options.add(kwargs['dest'])
|
||||
assert kwargs['default'] == [], 'The default is explicitly constructed as an empty list in resolve()'
|
||||
else:
|
||||
self.common_options.setdefault(suffix, set()).add(kwargs['dest'])
|
||||
kwargs['dest'] += suffix
|
||||
if not provide_defaults and 'default' in kwargs:
|
||||
# Interpolate help now, in case the %(default)d (or so) is mentioned,
|
||||
# to avoid producing incorrect help output.
|
||||
# Assumption: Interpolated output can safely be interpolated again,
|
||||
# which should always be the case.
|
||||
# Note: We control all inputs.
|
||||
kwargs['help'] = kwargs['help'] % kwargs
|
||||
if not is_append:
|
||||
kwargs['default'] = self.default_sentinel
|
||||
|
||||
common_group.add_argument(*args, **kwargs)
|
||||
|
||||
common_group = parser.add_argument_group('Common options')
|
||||
self.define_common_options(add_argument)
|
||||
|
||||
def resolve(self, args: argparse.Namespace): # Namespace has "in" but otherwise is not like a dict.
|
||||
"""
|
||||
Resolve the multiple definitions of each common option to the final value.
|
||||
"""
|
||||
for suffix in self.suffix_precedence:
|
||||
# From highest level to lowest level, so the "most-specific" option wins, e.g.
|
||||
# "borg --debug create --info" shall result in --info being effective.
|
||||
for dest in self.common_options.get(suffix, []):
|
||||
# map_from is this suffix' option name, e.g. log_level_subcommand
|
||||
# map_to is the target name, e.g. log_level
|
||||
map_from = dest + suffix
|
||||
map_to = dest
|
||||
# Retrieve value; depending on the action it may not exist, but usually does
|
||||
# (store_const/store_true/store_false), either because the action implied a default
|
||||
# or a default is explicitly supplied.
|
||||
# Note that defaults on lower levels are replaced with default_sentinel.
|
||||
# Only the top level has defaults.
|
||||
value = getattr(args, map_from, self.default_sentinel)
|
||||
if value is not self.default_sentinel:
|
||||
# value was indeed specified on this level. Transfer value to target,
|
||||
# and un-clobber the args (for tidiness - you *cannot* use the suffixed
|
||||
# names for other purposes, obviously).
|
||||
setattr(args, map_to, value)
|
||||
delattr(args, map_from)
|
||||
|
||||
# Options with an "append" action need some special treatment. Instead of
|
||||
# overriding values, all specified values are merged together.
|
||||
for dest in self.append_options:
|
||||
option_value = []
|
||||
for suffix in self.suffix_precedence:
|
||||
# Find values of this suffix, if any, and add them to the final list
|
||||
values = getattr(args, dest + suffix, [])
|
||||
option_value.extend(values)
|
||||
setattr(args, dest, option_value)
|
||||
|
||||
def build_parser(self):
|
||||
def process_epilog(epilog):
|
||||
epilog = textwrap.dedent(epilog).splitlines()
|
||||
|
|
@ -1881,156 +2001,53 @@ class Archiver:
|
|||
epilog = [line for line in epilog if not line.startswith('.. man')]
|
||||
return '\n'.join(epilog)
|
||||
|
||||
class CommonOptions:
|
||||
"""
|
||||
Support class to allow specifying common options directly after the top-level command.
|
||||
|
||||
Normally options can only be specified on the parser defining them, which means
|
||||
that generally speaking *all* options go after all sub-commands. This is annoying
|
||||
for common options in scripts, e.g. --remote-path or logging options.
|
||||
|
||||
This class allows adding the same set of options to both the top-level parser
|
||||
and the final sub-command parsers (but not intermediary sub-commands, at least for now).
|
||||
|
||||
It does so by giving every option's target name ("dest") a suffix indicating it's level
|
||||
-- no two options in the parser hierarchy can have the same target --
|
||||
then, after parsing the command line, multiple definitions are resolved.
|
||||
|
||||
Defaults are handled by only setting them on the top-level parser and setting
|
||||
a sentinel object in all sub-parsers, which then allows to discern which parser
|
||||
supplied the option.
|
||||
"""
|
||||
|
||||
# From lowest precedence to highest precedence:
|
||||
# An option specified on the parser belonging to index 0 is overridden if the
|
||||
# same option is specified on any parser with a higher index.
|
||||
SUFFIX_PRECEDENCE = ('_maincommand', '_midcommand', '_subcommand')
|
||||
|
||||
def __init__(self):
|
||||
from collections import defaultdict
|
||||
|
||||
# Maps suffixes to sets of target names.
|
||||
# E.g. common_options["_subcommand"] = {..., "log_level", ...}
|
||||
self.common_options = defaultdict(defaultdict)
|
||||
self.append_options = set()
|
||||
self.default_sentinel = object()
|
||||
|
||||
def add_common_group(self, parser, suffix='_subcommand', provide_defaults=False):
|
||||
"""
|
||||
Add common options to *parser*.
|
||||
|
||||
*provide_defaults* must only be True exactly once in a parser hierarchy,
|
||||
at the top level, and False on all lower levels. The default is chosen
|
||||
accordingly.
|
||||
|
||||
*suffix* indicates the suffix to use internally. It also indicates
|
||||
which precedence the *parser* has for common options. See SUFFIX_PRECEDENCE.
|
||||
"""
|
||||
assert suffix in self.SUFFIX_PRECEDENCE
|
||||
|
||||
def add_argument(*args, **kwargs):
|
||||
if 'dest' in kwargs:
|
||||
is_append = kwargs.get('action') == 'append'
|
||||
if is_append:
|
||||
self.append_options.add(kwargs['dest'])
|
||||
assert kwargs['default'] == [], 'The default is explicitly constructed as an empty list in resolve()'
|
||||
else:
|
||||
self.common_options.setdefault(suffix, set()).add(kwargs['dest'])
|
||||
kwargs['dest'] += suffix
|
||||
if not provide_defaults and 'default' in kwargs:
|
||||
# Interpolate help now, in case the %(default)d (or so) is mentioned,
|
||||
# to avoid producing incorrect help output.
|
||||
# Assumption: Interpolated output can safely be interpolated again,
|
||||
# which should always be the case.
|
||||
# Note: We control all inputs.
|
||||
kwargs['help'] = kwargs['help'] % kwargs
|
||||
if not is_append:
|
||||
kwargs['default'] = self.default_sentinel
|
||||
|
||||
common_group.add_argument(*args, **kwargs)
|
||||
|
||||
common_group = parser.add_argument_group('Common options')
|
||||
|
||||
add_argument('-h', '--help', action='help', help='show this help message and exit')
|
||||
add_argument('--critical', dest='log_level',
|
||||
action='store_const', const='critical', default='warning',
|
||||
help='work on log level CRITICAL')
|
||||
add_argument('--error', dest='log_level',
|
||||
action='store_const', const='error', default='warning',
|
||||
help='work on log level ERROR')
|
||||
add_argument('--warning', dest='log_level',
|
||||
action='store_const', const='warning', default='warning',
|
||||
help='work on log level WARNING (default)')
|
||||
add_argument('--info', '-v', '--verbose', dest='log_level',
|
||||
action='store_const', const='info', default='warning',
|
||||
help='work on log level INFO')
|
||||
add_argument('--debug', dest='log_level',
|
||||
action='store_const', const='debug', default='warning',
|
||||
help='enable debug output, work on log level DEBUG')
|
||||
add_argument('--debug-topic', dest='debug_topics',
|
||||
action='append', metavar='TOPIC', default=[],
|
||||
help='enable TOPIC debugging (can be specified multiple times). '
|
||||
'The logger path is borg.debug.<TOPIC> if TOPIC is not fully qualified.')
|
||||
add_argument('-p', '--progress', dest='progress', action='store_true',
|
||||
help='show progress information')
|
||||
add_argument('--log-json', dest='log_json', action='store_true',
|
||||
help='Output one JSON object per log line instead of formatted text.')
|
||||
add_argument('--lock-wait', dest='lock_wait', type=int, metavar='N', default=1,
|
||||
help='wait for the lock, but max. N seconds (default: %(default)d).')
|
||||
add_argument('--show-version', dest='show_version', action='store_true', default=False,
|
||||
help='show/log the borg version')
|
||||
add_argument('--show-rc', dest='show_rc', action='store_true', default=False,
|
||||
help='show/log the return code (rc)')
|
||||
add_argument('--no-files-cache', dest='cache_files', action='store_false',
|
||||
help='do not load/update the file metadata cache used to detect unchanged files')
|
||||
add_argument('--umask', dest='umask', type=lambda s: int(s, 8), default=UMASK_DEFAULT, metavar='M',
|
||||
help='set umask to M (local and remote, default: %(default)04o)')
|
||||
add_argument('--remote-path', dest='remote_path', metavar='PATH',
|
||||
help='use PATH as borg executable on the remote (default: "borg")')
|
||||
add_argument('--remote-ratelimit', dest='remote_ratelimit', type=int, metavar='rate',
|
||||
help='set remote network upload rate limit in kiByte/s (default: 0=unlimited)')
|
||||
add_argument('--consider-part-files', dest='consider_part_files',
|
||||
action='store_true', default=False,
|
||||
help='treat part files like normal files (e.g. to list/extract them)')
|
||||
|
||||
def resolve(self, args: argparse.Namespace): # Namespace has "in" but otherwise is not like a dict.
|
||||
"""
|
||||
Resolve the multiple definitions of each common option to the final value.
|
||||
"""
|
||||
for suffix in self.SUFFIX_PRECEDENCE:
|
||||
# From highest level to lowest level, so the "most-specific" option wins, e.g.
|
||||
# "borg --debug create --info" shall result in --info being effective.
|
||||
for dest in self.common_options.get(suffix, []):
|
||||
# map_from is this suffix' option name, e.g. log_level_subcommand
|
||||
# map_to is the target name, e.g. log_level
|
||||
map_from = dest + suffix
|
||||
map_to = dest
|
||||
# Retrieve value; depending on the action it may not exist, but usually does
|
||||
# (store_const/store_true/store_false), either because the action implied a default
|
||||
# or a default is explicitly supplied.
|
||||
# Note that defaults on lower levels are replaced with default_sentinel.
|
||||
# Only the top level has defaults.
|
||||
value = getattr(args, map_from, self.default_sentinel)
|
||||
if value is not self.default_sentinel:
|
||||
# value was indeed specified on this level. Transfer value to target,
|
||||
# and un-clobber the args (for tidiness - you *cannot* use the suffixed
|
||||
# names for other purposes, obviously).
|
||||
setattr(args, map_to, value)
|
||||
delattr(args, map_from)
|
||||
|
||||
# Options with an "append" action need some special treatment. Instead of
|
||||
# overriding values, all specified values are merged together.
|
||||
for dest in self.append_options:
|
||||
option_value = []
|
||||
for suffix in self.SUFFIX_PRECEDENCE:
|
||||
# Find values of this suffix, if any, and add them to the final list
|
||||
values = getattr(args, dest + suffix, [])
|
||||
option_value.extend(values)
|
||||
setattr(args, dest, option_value)
|
||||
def define_common_options(add_common_option):
|
||||
add_common_option('-h', '--help', action='help', help='show this help message and exit')
|
||||
add_common_option('--critical', dest='log_level',
|
||||
action='store_const', const='critical', default='warning',
|
||||
help='work on log level CRITICAL')
|
||||
add_common_option('--error', dest='log_level',
|
||||
action='store_const', const='error', default='warning',
|
||||
help='work on log level ERROR')
|
||||
add_common_option('--warning', dest='log_level',
|
||||
action='store_const', const='warning', default='warning',
|
||||
help='work on log level WARNING (default)')
|
||||
add_common_option('--info', '-v', '--verbose', dest='log_level',
|
||||
action='store_const', const='info', default='warning',
|
||||
help='work on log level INFO')
|
||||
add_common_option('--debug', dest='log_level',
|
||||
action='store_const', const='debug', default='warning',
|
||||
help='enable debug output, work on log level DEBUG')
|
||||
add_common_option('--debug-topic', dest='debug_topics',
|
||||
action='append', metavar='TOPIC', default=[],
|
||||
help='enable TOPIC debugging (can be specified multiple times). '
|
||||
'The logger path is borg.debug.<TOPIC> if TOPIC is not fully qualified.')
|
||||
add_common_option('-p', '--progress', dest='progress', action='store_true',
|
||||
help='show progress information')
|
||||
add_common_option('--log-json', dest='log_json', action='store_true',
|
||||
help='Output one JSON object per log line instead of formatted text.')
|
||||
add_common_option('--lock-wait', dest='lock_wait', type=int, metavar='N', default=1,
|
||||
help='wait for the lock, but max. N seconds (default: %(default)d).')
|
||||
add_common_option('--show-version', dest='show_version', action='store_true', default=False,
|
||||
help='show/log the borg version')
|
||||
add_common_option('--show-rc', dest='show_rc', action='store_true', default=False,
|
||||
help='show/log the return code (rc)')
|
||||
add_common_option('--no-files-cache', dest='cache_files', action='store_false',
|
||||
help='do not load/update the file metadata cache used to detect unchanged files')
|
||||
add_common_option('--umask', dest='umask', type=lambda s: int(s, 8), default=UMASK_DEFAULT, metavar='M',
|
||||
help='set umask to M (local and remote, default: %(default)04o)')
|
||||
add_common_option('--remote-path', dest='remote_path', metavar='PATH',
|
||||
help='use PATH as borg executable on the remote (default: "borg")')
|
||||
add_common_option('--remote-ratelimit', dest='remote_ratelimit', type=int, metavar='rate',
|
||||
help='set remote network upload rate limit in kiByte/s (default: 0=unlimited)')
|
||||
add_common_option('--consider-part-files', dest='consider_part_files',
|
||||
action='store_true', default=False,
|
||||
help='treat part files like normal files (e.g. to list/extract them)')
|
||||
|
||||
parser = argparse.ArgumentParser(prog=self.prog, description='Borg - Deduplicated Backups',
|
||||
add_help=False)
|
||||
parser.common_options = CommonOptions()
|
||||
parser.common_options = self.CommonOptions(define_common_options,
|
||||
suffix_precedence=('_maincommand', '_midcommand', '_subcommand'))
|
||||
parser.add_argument('-V', '--version', action='version', version='%(prog)s ' + __version__,
|
||||
help='show version number and exit')
|
||||
parser.common_options.add_common_group(parser, '_maincommand', provide_defaults=True)
|
||||
|
|
|
|||
Loading…
Reference in New Issue