From 46ec6203d516ab2d8d4e27c5d285460afe1d8cc3 Mon Sep 17 00:00:00 2001 From: Satoru SATOH Date: Mon, 10 Aug 2015 00:53:56 +0900 Subject: [PATCH] add cli (anyconfig_cli) usage examples; may close the issue #20 --- docs/cli.rst | 330 +++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 306 insertions(+), 24 deletions(-) diff --git a/docs/cli.rst b/docs/cli.rst index 0e8aa152..940fef02 100644 --- a/docs/cli.rst +++ b/docs/cli.rst @@ -4,7 +4,11 @@ CLI Usage python-anyconfig contains a CLI frontend 'anyconfig_cli' to demonstrate the power of this library. -It can process various config files and output a merged config file: +It can process config files in any formats supported in your environment and: + +- output merged/converted config outputs w/ modifications needed +- output schema file for given inputs +- merge/convert input config and extract part of the config .. code-block:: console @@ -12,7 +16,8 @@ It can process various config files and output a merged config file: Usage: anyconfig_cli [Options...] CONF_PATH_OR_PATTERN_0 [CONF_PATH_OR_PATTERN_1 ..] Examples: - anyconfig_cli --list + anyconfig_cli --list # -> Supported config types: configobj, ini, json, ... + # Merge and/or convert input config to output config [file] anyconfig_cli -I yaml -O yaml /etc/xyz/conf.d/a.conf anyconfig_cli -I yaml '/etc/xyz/conf.d/*.conf' -o xyz.conf --otype json anyconfig_cli '/etc/xyz/conf.d/*.json' -o xyz.yml \ @@ -21,50 +26,327 @@ It can process various config files and output a merged config file: -A obsoletes:sysdata;conflicts:sysdata-old anyconfig_cli /etc/foo.json /etc/foo/conf.d/x.json /etc/foo/conf.d/y.json anyconfig_cli '/etc/foo.d/*.json' -M noreplace + # Get/set part of input config anyconfig_cli '/etc/foo.d/*.json' --get a.b.c anyconfig_cli '/etc/foo.d/*.json' --set a.b.c=1 Options: --version show program's version number and exit -h, --help show this help message and exit - -L, --list List supported config types -o OUTPUT, --output=OUTPUT Output file path -I ITYPE, --itype=ITYPE - Select type of Input config files from ini, json, xml, - yaml [Automatically detected by file ext] + Select type of Input config files from configobj, ini, + json, msgpack, xml, yaml [Automatically detected by + file ext] -O OTYPE, --otype=OTYPE - Select type of Output config files from ini, json, - xml, yaml [Automatically detected by file ext] + Select type of Output config files from configobj, + ini, json, msgpack, xml, yaml [Automatically detected + by file ext] -M MERGE, --merge=MERGE Select strategy to merge multiple configs from replace, noreplace, merge_dicts, merge_dicts_and_lists [merge_dicts] -A ARGS, --args=ARGS Argument configs to override --atype=ATYPE Explicitly select type of argument to provide configs - from ini, json, xml, yaml. If this option is not set, - original parser is used: 'K:V' will become {K: V}, - 'K:V_0,V_1,..' will become {K: [V_0, V_1, ...]}, and - 'K_0:V_0;K_1:V_1' will become {K_0: V_0, K_1: V_1} - (where the tyep of K is str, type of V is one of Int, - str, etc. - --get=GET Specify key path to get part of config, for example, ' - --get a.b.c' to config {'a': {'b': {'c': 0, 'd': 1}}} - gives 0 and '--get a.b' to the same config gives {'c': - 0, 'd': 1}. - --set=SET Specify key path to set (update) part of config, for - example, '--set a.b.c=1' to a config {'a': {'b': {'c': - 0, 'd': 1}}} gives {'a': {'b': {'c': 1, 'd': 1}}}. + from configobj, ini, json, msgpack, xml, yaml. If + this option is not set, original parser is used: 'K:V' + will become {K: V}, 'K:V_0,V_1,..' will become {K: + [V_0, V_1, ...]}, and 'K_0:V_0;K_1:V_1' will become + {K_0: V_0, K_1: V_1} (where the tyep of K is str, type + of V is one of Int, str, etc. -x, --ignore-missing Ignore missing input files - --template Enable template config support - --env Load configuration defaults from environment values + -T, --template Enable template config support + -E, --env Load configuration defaults from environment values -S SCHEMA, --schema=SCHEMA Specify Schema file[s] path - -V, --validate Only validate input files and do not output. You must - specify schema file with -S/--schema option. -s, --silent Silent or quiet mode -q, --quiet Same as --silent option -v, --verbose Verbose mode + + List specific options: + -L, --list List supported config types + + Schema specific options: + --validate Only validate input files and do not output. You must + specify schema file with -S/--schema option. + --gen-schema Generate JSON schema for givne config file[s] and + output it instead of (merged) configuration. + + Get/set options: + --get=GET Specify key path to get part of config, for example, ' + --get a.b.c' to config {'a': {'b': {'c': 0, 'd': 1}}} + gives 0 and '--get a.b' to the same config gives {'c': + 0, 'd': 1}. + --set=SET Specify key path to set (update) part of config, for + example, '--set a.b.c=1' to a config {'a': {'b': {'c': + 0, 'd': 1}}} gives {'a': {'b': {'c': 1, 'd': 1}}}. ssato@localhost% +List supported config types (formats) +--------------------------------------- + +anyconfig_cli lists config types (formats) supported in your environment with -L/--list option: + +.. code-block:: console + + $ anyconfig_cli -L + Supported config types: configobj, ini, json, msgpack, xml, yaml + $ anyconfig_cli --list + Supported config types: configobj, ini, json, msgpack, xml, yaml + $ + +Merge and/or convert input config +----------------------------------- + +anyconfig_cli can process a config file or config files and output merged +config in various formats it can support in your environment. + +Here are some such examples. + +- single input config file, input type is automatically detected from the input file's extension: + +.. code-block:: console + + $ cat /tmp/a.yml + a: 1 + b: + c: + - aaa + - bbb + d: + e: + f: xyz + g: true + $ anyconfig_cli -O json /tmp/a.yml + Loading: /tmp/a.yml + {"a": 1, "b": {"c": ["aaa", "bbb"]}, "d": {"e": {"g": true, "f": "xyz"}}} + +- single input config file with the input type and output option: + +.. code-block:: console + + $ diff -u /tmp/a.{yml,conf} + $ anyconfig_cli -I yaml -O configobj /tmp/a.conf -o /tmp/a.ini --silent + $ cat /tmp/a.ini + a = 1 + [b] + c = aaa, bbb + [d] + [[e]] + g = True + f = xyz + $ + +- multiple input config files: + +.. code-block:: console + + $ cat /tmp/b.yml + b: + i: + j: 123 + d: + e: + g: hello, world + l: -1 + $ anyconfig_cli /tmp/{a,b}.yml --silent + a: 1 + b: + c: [aaa, bbb] + i: {j: 123} + d: + e: {f: xyz, g: 'hello, world'} + l: -1 + + $ + +- multiple input config files with merge strategy option: + +.. code-block:: console + + $ anyconfig_cli /tmp/{a,b}.yml -M replace --silent + a: 1 + b: + i: {j: 123} + d: + e: {g: 'hello, world'} + l: -1 + + $ + +- multiple input config files with template option: + +.. code-block:: console + + $ cat /tmp/c.yml + m: {{ d.e.g }} + n: {{ b.i.j }} + $ anyconfig_cli /tmp/{a,b,c}.yml --silent --template + a: 1 + b: + c: [aaa, bbb] + i: {j: 123} + d: + e: {f: xyz, g: 'hello, world'} + l: -1 + m: hello, world + n: 123 + + $ ls /tmp/*.yml + /tmp/a.yml /tmp/b.yml /tmp/c.yml + $ # Same as the privious one but inputs are given in a glob pattern. + $ anyconfig_cli '/tmp/*.yml' --silent --template # same as the privious one + a: 1 + b: + c: [aaa, bbb] + i: {j: 123} + d: + e: {f: xyz, g: 'hello, world'} + l: -1 + m: hello, world + n: 123 + + $ + +- Missing input config files: + +.. code-block:: console + + $ ls /tmp/not-exist-file.yml + ls: cannot access /tmp/not-exist-file.yml: No such file or directory + $ anyconfig_cli --ignore-missing /tmp/not-exist-file.yml -s + {} + + $ anyconfig_cli --ignore-missing /tmp/not-exist-file.yml -s -A "a: aaa" + No config type was given. Try to parse... + {a: aaa} + + $ anyconfig_cli --ignore-missing /tmp/not-exist-file.yml -s -A "a: aaa; b: 123" + No config type was given. Try to parse... + {a: aaa, b: 123} + + $ + +Schema generation and validation +---------------------------------- + +anyconfig_cli can process input config file[s] and generate JSON schema file to +validate the config like this: + +- An usage example of schema generation option --gen-schema of anyconfig_cli: + +.. code-block:: console + + $ cat /tmp/a.yml + a: 1 + b: + c: + - aaa + - bbb + d: + e: + f: xyz + g: true + $ anyconfig_cli --gen-schema /tmp/a.yml -s -o /tmp/a.schema.json + $ jq '.' /tmp/a.schema.json + { + "properties": { + "d": { + "properties": { + "e": { + "properties": { + "f": { + "type": "string" + }, + "g": { + "type": "boolean" + } + }, + "type": "object" + } + }, + "type": "object" + }, + "b": { + "properties": { + "c": { + "type": "array", + "items": { + "type": "string" + } + } + }, + "type": "object" + }, + "a": { + "type": "integer" + } + }, + "type": "object" + } + $ + +- and schema validation option --validate (and --schema) of anyconfig_cli: + +.. code-block:: console + + $ anyconfig_cli -A 'a: aaa' --atype yaml /tmp/a.yml -o /tmp/a2.yml --silent + $ head -n 1 /tmp/a.yml + a: 1 + $ head -n 1 /tmp/a2.yml + a: aaa + $ anyconfig_cli --validate --schema /tmp/a.schema.json /tmp/a.yml + Loading: /tmp/a.schema.json + Loading: /tmp/a.yml + Validation succeeds + $ anyconfig_cli --validate --schema /tmp/a.schema.json /tmp/a.yml -s; echo $? + 0 + $ anyconfig_cli --validate --schema /tmp/a.schema.json /tmp/a2.yml -s; echo $? + 'aaa' is not of type u'integer' + + Failed validating u'type' in schema[u'properties'][u'a']: + {u'type': u'integer'} + + On instance[u'a']: + 'aaa' + Validation failed1 + $ + +Get/set - extract or set part of input config +------------------------------------------------ + +Here is usage examples of --get option of anyconfig_cli: + +.. code-block:: console + + $ cat /tmp/a.yml + a: 1 + b: + c: + - aaa + - bbb + d: + e: + f: xyz + g: true + $ anyconfig_cli /tmp/a.yml --get d.e.f --silent + xyz + $ anyconfig_cli /tmp/a.yml --get b.c --silent + ['aaa', 'bbb'] + $ + +and an usage example of --set option of anyconfig_cli with same input: + +.. code-block:: console + + $ anyconfig_cli /tmp/a.yml --set "d.e.g=1000" --set "b.c=ccc," --silent + a: 1 + b: + c: [ccc] + d: + e: {f: xyz, g: true} + + $ + .. vim:sw=2:ts=2:et: