ungleich-public/cdist
ungleich-public
/
cdist
7
3
Fork 10
Code Issues 57 Pull Requests 12 Projects Releases Wiki Activity

Cleanup options' help and cdist man page.

This commit is contained in:
Darko Poljak 2017-08-17 08:24:58 +02:00
parent eb01c5bb85
commit 982bb286f4
2 changed files with 89 additions and 112 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

89
cdist/argparse.py
View File

@ -27,6 +27,17 @@ _verbosity_level = {
3: logging.DEBUG, 3: logging.DEBUG,
4: logging.TRACE, 4: logging.TRACE,
} }
# Generate verbosity level constants:
# VERBOSE_OFF, VERBOSE_ERROR, VERBOSE_WARNING, VERBOSE_INFO, VERBOSE_VERBOSE,
# VERBOSE_DEBUG, VERBOSE_TRACE.
this_globals = globals()
for level in _verbosity_level:
const = 'VERBOSE_' + logging.getLevelName(_verbosity_level[level])
this_globals[const] = level
# All verbosity levels above 4 are TRACE. # All verbosity levels above 4 are TRACE.
_verbosity_level = collections.defaultdict( _verbosity_level = collections.defaultdict(
lambda: logging.TRACE, _verbosity_level) lambda: logging.TRACE, _verbosity_level)
@ -87,7 +98,7 @@ def get_parsers():
parser['loglevel'] = argparse.ArgumentParser(add_help=False) parser['loglevel'] = argparse.ArgumentParser(add_help=False)
parser['loglevel'].add_argument( parser['loglevel'].add_argument(
'-q', '--quiet', '-q', '--quiet',
help='Quiet mode: disables logging, including WARNING and ERROR', help='Quiet mode: disables logging, including WARNING and ERROR.',
action='store_true', default=False) action='store_true', default=False)
parser['loglevel'].add_argument( parser['loglevel'].add_argument(
'-v', '--verbose', '-v', '--verbose',
@ -102,16 +113,15 @@ def get_parsers():
parser['beta'] = argparse.ArgumentParser(add_help=False) parser['beta'] = argparse.ArgumentParser(add_help=False)
parser['beta'].add_argument( parser['beta'].add_argument(
'-b', '--beta', '-b', '--beta',
help=('Enable beta functionality. ' help=('Enable beta functionality. '),
'Can also be enabled using CDIST_BETA env var.'),
action='store_true', dest='beta', action='store_true', dest='beta',
default='CDIST_BETA' in os.environ) default=False)
# Main subcommand parser # Main subcommand parser
parser['main'] = argparse.ArgumentParser( parser['main'] = argparse.ArgumentParser(
description='cdist ' + cdist.VERSION, parents=[parser['loglevel']]) description='cdist ' + cdist.VERSION, parents=[parser['loglevel']])
parser['main'].add_argument( parser['main'].add_argument(
'-V', '--version', help='Show version', action='version', '-V', '--version', help='Show version.', action='version',
version='%(prog)s ' + cdist.VERSION) version='%(prog)s ' + cdist.VERSION)
parser['sub'] = parser['main'].add_subparsers( parser['sub'] = parser['main'].add_subparsers(
title="Commands", dest="command") title="Commands", dest="command")
@ -136,18 +146,17 @@ def get_parsers():
parser['config_main'] = argparse.ArgumentParser(add_help=False) parser['config_main'] = argparse.ArgumentParser(add_help=False)
parser['config_main'].add_argument( parser['config_main'].add_argument(
'-C', '--cache-path-pattern', '-C', '--cache-path-pattern',
help=('Specify custom cache path pattern. It can also be set ' help=('Specify custom cache path pattern. If '
'by CDIST_CACHE_PATH_PATTERN environment variable. If '
'it is not set then default hostdir is used.'), 'it is not set then default hostdir is used.'),
dest='cache_path_pattern', dest='cache_path_pattern',
default=os.environ.get('CDIST_CACHE_PATH_PATTERN')) default=None)
parser['config_main'].add_argument( parser['config_main'].add_argument(
'-c', '--conf-dir', '-c', '--conf-dir',
help=('Add configuration directory (can be repeated, ' help=('Add configuration directory (can be repeated, '
'last one wins)'), action='append') 'last one wins).'), action='append')
parser['config_main'].add_argument( parser['config_main'].add_argument(
'-i', '--initial-manifest', '-i', '--initial-manifest',
help='path to a cdist manifest or \'-\' to read from stdin.', help='Path to a cdist manifest or \'-\' to read from stdin.',
dest='manifest', required=False) dest='manifest', required=False)
parser['config_main'].add_argument( parser['config_main'].add_argument(
'-j', '--jobs', nargs='?', '-j', '--jobs', nargs='?',
@ -160,17 +169,18 @@ def get_parsers():
const=multiprocessing.cpu_count()) const=multiprocessing.cpu_count())
parser['config_main'].add_argument( parser['config_main'].add_argument(
'-n', '--dry-run', '-n', '--dry-run',
help='do not execute code', action='store_true') help='Do not execute code.', action='store_true')
parser['config_main'].add_argument( parser['config_main'].add_argument(
'-o', '--out-dir', '-o', '--out-dir',
help='directory to save cdist output in', dest="out_path") help='Directory to save cdist output in.', dest="out_path")
parser['config_main'].add_argument( parser['config_main'].add_argument(
'-R', '--use-archiving', nargs='?', '-R', '--use-archiving', nargs='?',
choices=('tar', 'tgz', 'tbz2', 'txz',), choices=('tar', 'tgz', 'tbz2', 'txz',),
help=('Operate by using archiving with compression where ' help=('Operate by using archiving with compression where '
'apropriate. Supported values are: tar - tar archive, ' 'apropriate. Supported values are: tar - tar archive, '
'tgz - gzip tar archive (the default), ' 'tgz - gzip tar archive (the default), '
'tbz2 - bzip2 tar archive and txz - lzma tar archive.'), 'tbz2 - bzip2 tar archive and txz - lzma tar archive. '
'Currently in beta.'),
action='store', dest='use_archiving', action='store', dest='use_archiving',
const='tgz') const='tgz')
@ -179,33 +189,33 @@ def get_parsers():
# parsing to determine implementation default # parsing to determine implementation default
parser['config_main'].add_argument( parser['config_main'].add_argument(
'-r', '--remote-out-dir', '-r', '--remote-out-dir',
help='Directory to save cdist output in on the target host', help='Directory to save cdist output in on the target host.',
dest="remote_out_path") dest="remote_out_path")
parser['config_main'].add_argument( parser['config_main'].add_argument(
'--remote-copy', '--remote-copy',
help='Command to use for remote copy (should behave like scp)', help='Command to use for remote copy (should behave like scp).',
action='store', dest='remote_copy', action='store', dest='remote_copy',
default=os.environ.get('CDIST_REMOTE_COPY')) default=None)
parser['config_main'].add_argument( parser['config_main'].add_argument(
'--remote-exec', '--remote-exec',
help=('Command to use for remote execution ' help=('Command to use for remote execution '
'(should behave like ssh)'), '(should behave like ssh).'),
action='store', dest='remote_exec', action='store', dest='remote_exec',
default=os.environ.get('CDIST_REMOTE_EXEC')) default=None)
# Config # Config
parser['config_args'] = argparse.ArgumentParser(add_help=False) parser['config_args'] = argparse.ArgumentParser(add_help=False)
parser['config_args'].add_argument( parser['config_args'].add_argument(
'-A', '--all-tagged', '-A', '--all-tagged',
help=('use all hosts present in tags db'), help=('Use all hosts present in tags db. Currently in beta.'),
action="store_true", dest="all_tagged_hosts", default=False) action="store_true", dest="all_tagged_hosts", default=False)
parser['config_args'].add_argument( parser['config_args'].add_argument(
'-a', '--all', '-a', '--all',
help=('list hosts that have all specified tags, ' help=('List hosts that have all specified tags, '
'if -t/--tag is specified'), 'if -t/--tag is specified.'),
action="store_true", dest="has_all_tags", default=False) action="store_true", dest="has_all_tags", default=False)
parser['config_args'].add_argument( parser['config_args'].add_argument(
'host', nargs='*', help='host(s) to operate on') 'host', nargs='*', help='Host(s) to operate on.')
parser['config_args'].add_argument( parser['config_args'].add_argument(
'-f', '--file', '-f', '--file',
help=('Read specified file for a list of additional hosts to ' help=('Read specified file for a list of additional hosts to '
@ -223,12 +233,13 @@ def get_parsers():
const=multiprocessing.cpu_count()) const=multiprocessing.cpu_count())
parser['config_args'].add_argument( parser['config_args'].add_argument(
'-s', '--sequential', '-s', '--sequential',
help='operate on multiple hosts sequentially (default)', help='Operate on multiple hosts sequentially (default).',
action='store_const', dest='parallel', const=0) action='store_const', dest='parallel', const=0)
parser['config_args'].add_argument( parser['config_args'].add_argument(
'-t', '--tag', '-t', '--tag',
help=('host is specified by tag, not hostname/address; ' help=('Host is specified by tag, not hostname/address; '
'list all hosts that contain any of specified tags'), 'list all hosts that contain any of specified tags. '
'Currently in beta.'),
dest='tag', required=False, action="store_true", default=False) dest='tag', required=False, action="store_true", default=False)
parser['config'] = parser['sub'].add_parser( parser['config'] = parser['sub'].add_parser(
'config', parents=[parser['loglevel'], parser['beta'], 'config', parents=[parser['loglevel'], parser['beta'],
@ -253,7 +264,7 @@ def get_parsers():
'add-host', parents=[parser['loglevel'], parser['beta'], 'add-host', parents=[parser['loglevel'], parser['beta'],
parser['inventory_common']]) parser['inventory_common']])
parser['add-host'].add_argument( parser['add-host'].add_argument(
'host', nargs='*', help='host(s) to add') 'host', nargs='*', help='Host(s) to add.')
parser['add-host'].add_argument( parser['add-host'].add_argument(
'-f', '--file', '-f', '--file',
help=('Read additional hosts to add from specified file ' help=('Read additional hosts to add from specified file '
@ -267,7 +278,7 @@ def get_parsers():
parser['inventory_common']]) parser['inventory_common']])
parser['add-tag'].add_argument( parser['add-tag'].add_argument(
'host', nargs='*', 'host', nargs='*',
help='list of host(s) for which tags are added') help='List of host(s) for which tags are added.')
parser['add-tag'].add_argument( parser['add-tag'].add_argument(
'-f', '--file', '-f', '--file',
help=('Read additional hosts to add tags from specified file ' help=('Read additional hosts to add tags from specified file '
@ -289,16 +300,16 @@ def get_parsers():
parser['add-tag'].add_argument( parser['add-tag'].add_argument(
'-t', '--taglist', '-t', '--taglist',
help=("Tag list to be added for specified host(s), comma separated" help=("Tag list to be added for specified host(s), comma separated"
" values"), " values."),
dest="taglist", required=False) dest="taglist", required=False)
parser['del-host'] = parser['invsub'].add_parser( parser['del-host'] = parser['invsub'].add_parser(
'del-host', parents=[parser['loglevel'], parser['beta'], 'del-host', parents=[parser['loglevel'], parser['beta'],
parser['inventory_common']]) parser['inventory_common']])
parser['del-host'].add_argument( parser['del-host'].add_argument(
'host', nargs='*', help='host(s) to delete') 'host', nargs='*', help='Host(s) to delete.')
parser['del-host'].add_argument( parser['del-host'].add_argument(
'-a', '--all', help=('Delete all hosts'), '-a', '--all', help=('Delete all hosts.'),
dest='all', required=False, action="store_true", default=False) dest='all', required=False, action="store_true", default=False)
parser['del-host'].add_argument( parser['del-host'].add_argument(
'-f', '--file', '-f', '--file',
@ -313,10 +324,10 @@ def get_parsers():
parser['inventory_common']]) parser['inventory_common']])
parser['del-tag'].add_argument( parser['del-tag'].add_argument(
'host', nargs='*', 'host', nargs='*',
help='list of host(s) for which tags are deleted') help='List of host(s) for which tags are deleted.')
parser['del-tag'].add_argument( parser['del-tag'].add_argument(
'-a', '--all', '-a', '--all',
help=('Delete all tags for specified host(s)'), help=('Delete all tags for specified host(s).'),
dest='all', required=False, action="store_true", default=False) dest='all', required=False, action="store_true", default=False)
parser['del-tag'].add_argument( parser['del-tag'].add_argument(
'-f', '--file', '-f', '--file',
@ -339,18 +350,18 @@ def get_parsers():
parser['del-tag'].add_argument( parser['del-tag'].add_argument(
'-t', '--taglist', '-t', '--taglist',
help=("Tag list to be deleted for specified host(s), " help=("Tag list to be deleted for specified host(s), "
"comma separated values"), "comma separated values."),
dest="taglist", required=False) dest="taglist", required=False)
parser['list'] = parser['invsub'].add_parser( parser['list'] = parser['invsub'].add_parser(
'list', parents=[parser['loglevel'], parser['beta'], 'list', parents=[parser['loglevel'], parser['beta'],
parser['inventory_common']]) parser['inventory_common']])
parser['list'].add_argument( parser['list'].add_argument(
'host', nargs='*', help='host(s) to list') 'host', nargs='*', help='Host(s) to list.')
parser['list'].add_argument( parser['list'].add_argument(
'-a', '--all', '-a', '--all',
help=('list hosts that have all specified tags, ' help=('List hosts that have all specified tags, '
'if -t/--tag is specified'), 'if -t/--tag is specified.'),
action="store_true", dest="has_all_tags", default=False) action="store_true", dest="has_all_tags", default=False)
parser['list'].add_argument( parser['list'].add_argument(
'-f', '--file', '-f', '--file',
@ -359,12 +370,12 @@ def get_parsers():
'If no host or host file is specified then, by default, ' 'If no host or host file is specified then, by default, '
'list all.'), dest='hostfile', required=False) 'list all.'), dest='hostfile', required=False)
parser['list'].add_argument( parser['list'].add_argument(
'-H', '--host-only', help=('Suppress tags listing'), '-H', '--host-only', help=('Suppress tags listing.'),
action="store_true", dest="list_only_host", default=False) action="store_true", dest="list_only_host", default=False)
parser['list'].add_argument( parser['list'].add_argument(
'-t', '--tag', '-t', '--tag',
help=('host is specified by tag, not hostname/address; ' help=('Host is specified by tag, not hostname/address; '
'list all hosts that contain any of specified tags'), 'list all hosts that contain any of specified tags.'),
action="store_true", default=False) action="store_true", default=False)
parser['inventory'].set_defaults( parser['inventory'].set_defaults(

112
docs/src/man1/cdist.rst
View File

@ -71,11 +71,11 @@ All commands accept the following options:
.. option:: -h, --help .. option:: -h, --help
Show the help screen Show the help screen.
.. option:: -q, --quiet .. option:: -q, --quiet
Quiet mode: disables logging, including WARNING and ERROR Quiet mode: disables logging, including WARNING and ERROR.
.. option:: -v, --verbose .. option:: -v, --verbose
@ -86,7 +86,7 @@ All commands accept the following options:
.. option:: -V, --version .. option:: -V, --version
Show version and exit Show version and exit.
BANNER BANNER
@ -98,26 +98,24 @@ cdist posters - a must have for every office.
CONFIG/INSTALL CONFIG/INSTALL
-------------- --------------
Configure/install one or more hosts. Configure/install one or more hosts.
Install command is currently in beta.
.. option:: -A, --all-tagged .. option:: -A, --all-tagged
use all hosts present in tags db Use all hosts present in tags db. Currently in beta.
.. option:: -a, --all .. option:: -a, --all
list hosts that have all specified tags, if -t/--tag List hosts that have all specified tags, if -t/--tag
is specified is specified.
.. option:: -b, --beta .. option:: -b, --beta
Enable beta functionality. Enable beta functionality.
Can also be enabled using CDIST_BETA env var.
.. option:: -C CACHE_PATH_PATTERN, --cache-path-pattern CACHE_PATH_PATTERN .. option:: -C CACHE_PATH_PATTERN, --cache-path-pattern CACHE_PATH_PATTERN
Sepcify custom cache path pattern. It can also be set by Sepcify custom cache path pattern. If it is not set then
CDIST_CACHE_PATH_PATTERN environment variable. If it is not set then
default hostdir is used. For more info on format see default hostdir is used. For more info on format see
:strong:`CACHE PATH PATTERN FORMAT` below. :strong:`CACHE PATH PATTERN FORMAT` below.
@ -125,11 +123,7 @@ Configure/install one or more hosts.
Add a configuration directory. Can be specified multiple times. Add a configuration directory. Can be specified multiple times.
If configuration directories contain conflicting types, explorers or If configuration directories contain conflicting types, explorers or
manifests, then the last one found is used. Additionally this can also manifests, then the last one found is used.
be configured by setting the CDIST_PATH environment variable to a colon
delimited list of config directories. Directories given with the
--conf-dir argument have higher precedence over those set through the
environment variable.
.. option:: -f HOSTFILE, --file HOSTFILE .. option:: -f HOSTFILE, --file HOSTFILE
@ -151,7 +145,7 @@ Configure/install one or more hosts.
.. option:: -i MANIFEST, --initial-manifest MANIFEST .. option:: -i MANIFEST, --initial-manifest MANIFEST
Path to a cdist manifest or - to read from stdin Path to a cdist manifest or - to read from stdin.
.. option:: -j [JOBS], --jobs [JOBS] .. option:: -j [JOBS], --jobs [JOBS]
@ -162,11 +156,11 @@ Configure/install one or more hosts.
.. option:: -n, --dry-run .. option:: -n, --dry-run
Do not execute code Do not execute code.
.. option:: -o OUT_PATH, --out-dir OUT_PATH .. option:: -o OUT_PATH, --out-dir OUT_PATH
Directory to save cdist output in Directory to save cdist output in.
.. option:: -p [HOST_MAX], --parallel [HOST_MAX] .. option:: -p [HOST_MAX], --parallel [HOST_MAX]
@ -179,29 +173,29 @@ Configure/install one or more hosts.
Operate by using archiving with compression where Operate by using archiving with compression where
apropriate. Supported values are: tar - tar archive, apropriate. Supported values are: tar - tar archive,
tgz - gzip tar archive (the default), tbz2 - bzip2 tar tgz - gzip tar archive (the default), tbz2 - bzip2 tar
archive and txz - lzma tar archive. archive and txz - lzma tar archive. Currently in beta.
.. option:: -r REMOTE_OUT_PATH, --remote-out-dir REMOTE_OUT_PATH .. option:: -r REMOTE_OUT_PATH, --remote-out-dir REMOTE_OUT_PATH
Directory to save cdist output in on the target host Directory to save cdist output in on the target host.
.. option:: -s, --sequential .. option:: -s, --sequential
Operate on multiple hosts sequentially (default) Operate on multiple hosts sequentially (default).
.. option:: --remote-copy REMOTE_COPY .. option:: --remote-copy REMOTE_COPY
Command to use for remote copy (should behave like scp) Command to use for remote copy (should behave like scp).
.. option:: --remote-exec REMOTE_EXEC .. option:: --remote-exec REMOTE_EXEC
Command to use for remote execution (should behave like ssh) Command to use for remote execution (should behave like ssh).
.. option:: -t, --tag .. option:: -t, --tag
host is specified by tag, not hostname/address; list Host is specified by tag, not hostname/address; list
all hosts that contain any of specified tags all hosts that contain any of specified tags.
Currently in beta.
HOSTFILE FORMAT HOSTFILE FORMAT
~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~
@ -247,16 +241,11 @@ Add host(s) to inventory database.
.. option:: host .. option:: host
host(s) to add Host(s) to add.
.. option:: -b, --beta .. option:: -b, --beta
Enable beta functionalities. Beta functionalities Enable beta functionality.
include inventory command with all sub-commands and
all options; config sub-command options: -j/--jobs,
-t/--tag, -a/--all.
Can also be enabled using CDIST_BETA env var.
.. option:: -f HOSTFILE, --file HOSTFILE .. option:: -f HOSTFILE, --file HOSTFILE
@ -265,9 +254,6 @@ Add host(s) to inventory database.
host or host file is specified then, by default, read host or host file is specified then, by default, read
from stdin. Hostfile format is the same as config hostfile format. from stdin. Hostfile format is the same as config hostfile format.
.. option:: -h, --help
show this help message and exit
.. option:: -I INVENTORY_DIR, --inventory INVENTORY_DIR .. option:: -I INVENTORY_DIR, --inventory INVENTORY_DIR
@ -286,16 +272,11 @@ Add tag(s) to inventory database.
.. option:: host .. option:: host
list of host(s) for which tags are added List of host(s) for which tags are added.
.. option:: -b, --beta .. option:: -b, --beta
Enable beta functionalities. Beta functionalities Enable beta functionality.
include inventory command with all sub-commands and
all options; config sub-command options: -j/--jobs,
-t/--tag, -a/--all.
Can also be enabled using CDIST_BETA env var.
.. option:: -f HOSTFILE, --file HOSTFILE .. option:: -f HOSTFILE, --file HOSTFILE
@ -328,7 +309,7 @@ Add tag(s) to inventory database.
.. option:: -t TAGLIST, --taglist TAGLIST .. option:: -t TAGLIST, --taglist TAGLIST
Tag list to be added for specified host(s), comma Tag list to be added for specified host(s), comma
separated values separated values.
INVENTORY DEL-HOST INVENTORY DEL-HOST
@ -337,20 +318,15 @@ Delete host(s) from inventory database.
.. option:: host .. option:: host
host(s) to delete Host(s) to delete.
.. option:: -a, --all .. option:: -a, --all
Delete all hosts Delete all hosts.
.. option:: -b, --beta .. option:: -b, --beta
Enable beta functionalities. Beta functionalities Enable beta functionality.
include inventory command with all sub-commands and
all options; config sub-command options: -j/--jobs,
-t/--tag, -a/--all.
Can also be enabled using CDIST_BETA env var.
.. option:: -f HOSTFILE, --file HOSTFILE .. option:: -f HOSTFILE, --file HOSTFILE
@ -376,20 +352,15 @@ Delete tag(s) from inventory database.
.. option:: host .. option:: host
list of host(s) for which tags are deleted List of host(s) for which tags are deleted.
.. option:: -a, --all .. option:: -a, --all
Delete all tags for specified host(s) Delete all tags for specified host(s).
.. option:: -b, --beta .. option:: -b, --beta
Enable beta functionalities. Beta functionalities Enable beta functionality.
include inventory command with all sub-commands and
all options; config sub-command options: -j/--jobs,
-t/--tag, -a/--all.
Can also be enabled using CDIST_BETA env var.
.. option:: -f HOSTFILE, --file HOSTFILE .. option:: -f HOSTFILE, --file HOSTFILE
@ -423,7 +394,7 @@ Delete tag(s) from inventory database.
.. option:: -t TAGLIST, --taglist TAGLIST .. option:: -t TAGLIST, --taglist TAGLIST
Tag list to be deleted for specified host(s), comma Tag list to be deleted for specified host(s), comma
separated values separated values.
INVENTORY LIST INVENTORY LIST
@ -432,21 +403,16 @@ List inventory database.
.. option:: host .. option:: host
host(s) to list Host(s) to list.
.. option:: -a, --all .. option:: -a, --all
list hosts that have all specified tags, if -t/--tag List hosts that have all specified tags, if -t/--tag
is specified is specified.
.. option:: -b, --beta .. option:: -b, --beta
Enable beta functionalities. Beta functionalities Enable beta functionality.
include inventory command with all sub-commands and
all options; config sub-command options: -j/--jobs,
-t/--tag, -a/--all.
Can also be enabled using CDIST_BETA env var.
.. option:: -f HOSTFILE, --file HOSTFILE .. option:: -f HOSTFILE, --file HOSTFILE
@ -457,7 +423,7 @@ List inventory database.
.. option:: -H, --host-only .. option:: -H, --host-only
Suppress tags listing Suppress tags listing.
.. option:: -I INVENTORY_DIR, --inventory INVENTORY_DIR .. option:: -I INVENTORY_DIR, --inventory INVENTORY_DIR
@ -471,8 +437,8 @@ List inventory database.
.. option:: -t, --tag .. option:: -t, --tag
host is specified by tag, not hostname/address; list Host is specified by tag, not hostname/address; list
all hosts that contain any of specified tags all hosts that contain any of specified tags.
SHELL SHELL