| Name | yaml-extender JSON |
| Version |
0.3.2
JSON |
| download |
| home_page | None |
| Summary | Extends the common .yaml syntax to provide more complex configuration options |
| upload_time | 2024-04-09 17:25:28 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | None |
| license | BSD 3-Clause License Copyright (c) 2023, Simon Gallitscher All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
| keywords |
yaml
configuration
extension
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
|
===============================================================================
yaml-extender
===============================================================================
.. contents:: :local:
Description
-----------
Extends the common .yaml syntax to provide more complex configuration options.
The yaml_extender can be used to resolve the extended yaml syntax as shown in Usage.rst.
The following options for extended yaml syntax are available.
For more examples on how to use, check the unittests in tests/ directory.
References
----------
Yaml values can be referenced by using ``{{ref}}``
More specific values from dictionaries can be accessed by separating references with a dot ``{{ref.subref}}``
You can access array elements by specifying the index separated by a dot. ``{{ref.1}}``
**Simple Example**::
my_reference: test_value
my_path: path/to/my/{{ my_reference }}
copy_reference: "{{my_reference}}"
my_config: path/to/{{ configured_value:default.cfg }}
Results in::
my_reference: test_value
my_path: path/to/my/test_value
copy_reference: test_value
my_config: path/to/default.cfg
More complex references can be done using dictionaries as well as lists.
**Complex Example**::
ref_val_1: "{{dict_1.subvalue_2.0.config}}"
ref_val_2: "{{dict_1.subvalue_2.1.path}}"
ref_val_3: "{{dict_1.subvalue_2.2.path:default_value}}"
dict_1:
subvalue_1: const_val
subvalue_2:
- path: first/path
config: first.cfg
- path: second/path
config: second.cfg
Results in::
ref_val_1: first.cfg
ref_val_2: second/path
ref_val_3: default_value
dict_1:
subvalue_1: const_val
subvalue_2:
- path: first/path
config: first.cfg
- path: second/path
config: second.cfg
Additionally a default value can be given using a colon symbol within the reference ``{{ref:default}}``
Example::
ref_val_1: {{ not_existing:123 }}
results in::
ref_val_1: 123
Lists
~~~~~
When accessing lists without specifying an index, they will automatically get joined together with a whitespace.
Example::
array_1:
- a
- b
- c
ref_val_1: {{ array_1 }}
results in::
array_1:
- a
- b
- c
ref_val_1: a b c
This can be done similar with list of dictionaries::
array_1:
- first: a
second: 1
- first: b
second: 2
firsts: {{array_1.first}}
seconds: {{array_1.second}}
Resulting in::
array_1:
- first: a
second: 1
- first: b
second: 2
firsts: a b
seconds: 1 2
Environment variables
~~~~~~~~~~~~~~~~~~~~~
In extended yaml syntax environment variables can be referenced using the key ``xyml.env``.
An Environment ENV_VAR variable can be referenced like this::
my_value: echo environment variable = {{ xyml.env.ENV_VAR}}
.. _parameters:
Parameters
~~~~~~~~~~
In extended yaml syntax additional parameters can be referenced using the key ``xyml.param``.
When including yaml_extender in another python script the parameters can be passed as dictionary when creating a XYmlFile object.
When using yaml_extender over command line all named parameters will be used to resolve ``xyml.param`` statements.
**Warning**
Only named parameters are allowed, positional arguments will cause problems.
An parameter given as "--my_param 123" or {"my_param": 123} can be referenced like this::
my_value: echo This is a parameter {{ xyml.param.my_param }}
Includes
--------
Yaml files can include other .yaml files by using the ``xyml.include: file.yaml`` statement.
Additionally all reference values within the included file can be overwritten using parameters.
Parameters are contained within the include statement ``xyml.include: file.yaml<<my_ref=param1>>``
Example
~~~~~~~
root.yaml::
ref_1: value1
dict_1:
subvalue_1: abc
xyml.include:
- file1.yaml<<ref_1=456>>
- file2.yaml
file1.yaml::
subvalue_2: 123
subvalue_3: {{ref_1}}
file2.yaml::
subvalue_4:
- abc
- xyz
**Results in**::
ref_1: value1
dict_1:
subvalue_1: abc
subvalue_2: 123
subvalue_3: 456
subvalue_4:
- abc
- xyz
**Note:**
It is also allowed to use ref values within include paths like this::
my_dir: path/to/my/dir
xyml.include: "{{my_dir}}/inc.yaml"
For loops
---------
Certain entries in your config can be repeated based on array values in you config.
You can directly repeat dictionary values by adding a ``xyml.loop`` statement.
Of course subvalues can be accessed in the same way as in normal references.
**Example:**::
array_1:
- value: abc
path: first/path
- value: xyz
path: second/path
commands:
xyml.for: iterator:array_1
cmd: sh {{ iterator.value }}
from: "{{ iterator.path }}"
will result in::
array_1:
- value: abc
path: first/path
- value: xyz
path: second/path
commands:
- cmd: sh abc
from: first/path
- cmd: sh xyz
from: second/path
Flat Loops
~~~~~~~~~~
Loops can also flatten itself. If you want to repeat arrays you can use the keyword ``xyml.content`` to provide the content of the loop.
**Example**::
array_1:
- abc
- xyz
commands:
xyml.for: iterator:array_1
xyml.content:
- cmd: sh {{ iterator }}
- cmd: echo {{ iterator }}
Will result in::
array_1:
- abc
- xyz
commands:
- cmd: sh abc
- cmd: echo abc
- cmd: sh xyz
- cmd: echo xyz
Loops for Permutation
~~~~~~~~~~~~~~~~~~~~~
Loops can also be used to create permutations. To simplify that a loop statement can take a custom amount of iterators.
**Example**::
array_1:
- abc
- xyz
array_2:
- 123
- 456
commands:
xyml.for: i:array_1, j:array_2
xyml.content:
- cmd: sh {{ i }} {{ j }}
Will result in::
array_1:
- abc
- xyz
array_2:
- 123
- 456
commands:
- cmd: sh abc 123
- cmd: sh abc 456
- cmd: sh xyz 123
- cmd: sh xyz 456
Inline Loops
~~~~~~~~~~~~~~~~~~~~~
You can also use loops to improve the string values in your configuration.
This can be used to simplify reoccurring values like parameters.
**Example**::
array_1:
- abc
- xyz
command: Input parameters: {{xyml.for:param:array_1:-i {{param}}}}
Will result in::
array_1:
- abc
- xyz
command: Input parameters: -i abc -i xyz
Raw data
{
"_id": null,
"home_page": null,
"name": "yaml-extender",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "yaml, configuration, extension",
"author": null,
"author_email": "Simon Gallitscher <adun.sg@gmx.de>",
"download_url": "https://files.pythonhosted.org/packages/bd/89/5a1059c75254aba9571c23c6779215ede1f7b1e7bab7e405d047e30a7659/yaml-extender-0.3.2.tar.gz",
"platform": null,
"description": "===============================================================================\r\nyaml-extender\r\n===============================================================================\r\n\r\n.. contents:: :local:\r\n\r\n\r\nDescription\r\n-----------\r\nExtends the common .yaml syntax to provide more complex configuration options.\r\nThe yaml_extender can be used to resolve the extended yaml syntax as shown in Usage.rst.\r\nThe following options for extended yaml syntax are available.\r\n\r\nFor more examples on how to use, check the unittests in tests/ directory.\r\n\r\nReferences\r\n----------\r\n\r\nYaml values can be referenced by using ``{{ref}}``\r\nMore specific values from dictionaries can be accessed by separating references with a dot ``{{ref.subref}}``\r\nYou can access array elements by specifying the index separated by a dot. ``{{ref.1}}``\r\n\r\n**Simple Example**::\r\n\r\n my_reference: test_value\r\n my_path: path/to/my/{{ my_reference }}\r\n copy_reference: \"{{my_reference}}\"\r\n my_config: path/to/{{ configured_value:default.cfg }}\r\n\r\nResults in::\r\n\r\n my_reference: test_value\r\n my_path: path/to/my/test_value\r\n copy_reference: test_value\r\n my_config: path/to/default.cfg\r\n\r\nMore complex references can be done using dictionaries as well as lists.\r\n\r\n**Complex Example**::\r\n\r\n ref_val_1: \"{{dict_1.subvalue_2.0.config}}\"\r\n ref_val_2: \"{{dict_1.subvalue_2.1.path}}\"\r\n ref_val_3: \"{{dict_1.subvalue_2.2.path:default_value}}\"\r\n dict_1:\r\n subvalue_1: const_val\r\n subvalue_2:\r\n - path: first/path\r\n config: first.cfg\r\n - path: second/path\r\n config: second.cfg\r\n\r\nResults in::\r\n\r\n ref_val_1: first.cfg\r\n ref_val_2: second/path\r\n ref_val_3: default_value\r\n dict_1:\r\n subvalue_1: const_val\r\n subvalue_2:\r\n - path: first/path\r\n config: first.cfg\r\n - path: second/path\r\n config: second.cfg\r\n\r\n\r\nAdditionally a default value can be given using a colon symbol within the reference ``{{ref:default}}``\r\nExample::\r\n\r\n ref_val_1: {{ not_existing:123 }}\r\n\r\nresults in::\r\n\r\n ref_val_1: 123\r\n\r\nLists\r\n~~~~~\r\n\r\nWhen accessing lists without specifying an index, they will automatically get joined together with a whitespace.\r\n\r\nExample::\r\n\r\n array_1:\r\n - a\r\n - b\r\n - c\r\n ref_val_1: {{ array_1 }}\r\n\r\nresults in::\r\n\r\n array_1:\r\n - a\r\n - b\r\n - c\r\n ref_val_1: a b c\r\n\r\nThis can be done similar with list of dictionaries::\r\n\r\n array_1:\r\n - first: a\r\n second: 1\r\n - first: b\r\n second: 2\r\n firsts: {{array_1.first}}\r\n seconds: {{array_1.second}}\r\n\r\nResulting in::\r\n\r\n array_1:\r\n - first: a\r\n second: 1\r\n - first: b\r\n second: 2\r\n firsts: a b\r\n seconds: 1 2\r\n\r\nEnvironment variables\r\n~~~~~~~~~~~~~~~~~~~~~\r\n\r\nIn extended yaml syntax environment variables can be referenced using the key ``xyml.env``.\r\n\r\nAn Environment ENV_VAR variable can be referenced like this::\r\n\r\n my_value: echo environment variable = {{ xyml.env.ENV_VAR}}\r\n\r\n\r\n.. _parameters:\r\n\r\nParameters\r\n~~~~~~~~~~\r\nIn extended yaml syntax additional parameters can be referenced using the key ``xyml.param``.\r\n\r\nWhen including yaml_extender in another python script the parameters can be passed as dictionary when creating a XYmlFile object.\r\nWhen using yaml_extender over command line all named parameters will be used to resolve ``xyml.param`` statements.\r\n\r\n**Warning**\r\nOnly named parameters are allowed, positional arguments will cause problems.\r\n\r\nAn parameter given as \"--my_param 123\" or {\"my_param\": 123} can be referenced like this::\r\n\r\n my_value: echo This is a parameter {{ xyml.param.my_param }}\r\n\r\n\r\nIncludes\r\n--------\r\n\r\nYaml files can include other .yaml files by using the ``xyml.include: file.yaml`` statement.\r\nAdditionally all reference values within the included file can be overwritten using parameters.\r\nParameters are contained within the include statement ``xyml.include: file.yaml<<my_ref=param1>>``\r\n\r\nExample\r\n~~~~~~~\r\n\r\nroot.yaml::\r\n\r\n ref_1: value1\r\n dict_1:\r\n subvalue_1: abc\r\n xyml.include:\r\n - file1.yaml<<ref_1=456>>\r\n - file2.yaml\r\n\r\nfile1.yaml::\r\n\r\n subvalue_2: 123\r\n subvalue_3: {{ref_1}}\r\n\r\nfile2.yaml::\r\n\r\n subvalue_4:\r\n - abc\r\n - xyz\r\n\r\n**Results in**::\r\n\r\n ref_1: value1\r\n dict_1:\r\n subvalue_1: abc\r\n subvalue_2: 123\r\n subvalue_3: 456\r\n subvalue_4:\r\n - abc\r\n - xyz\r\n\r\n\r\n**Note:**\r\nIt is also allowed to use ref values within include paths like this::\r\n\r\n my_dir: path/to/my/dir\r\n xyml.include: \"{{my_dir}}/inc.yaml\"\r\n\r\n\r\nFor loops\r\n---------\r\n\r\nCertain entries in your config can be repeated based on array values in you config.\r\nYou can directly repeat dictionary values by adding a ``xyml.loop`` statement.\r\nOf course subvalues can be accessed in the same way as in normal references.\r\n\r\n**Example:**::\r\n\r\n array_1:\r\n - value: abc\r\n path: first/path\r\n - value: xyz\r\n path: second/path\r\n\r\n commands:\r\n xyml.for: iterator:array_1\r\n cmd: sh {{ iterator.value }}\r\n from: \"{{ iterator.path }}\"\r\n\r\n\r\nwill result in::\r\n\r\n array_1:\r\n - value: abc\r\n path: first/path\r\n - value: xyz\r\n path: second/path\r\n\r\n commands:\r\n - cmd: sh abc\r\n from: first/path\r\n - cmd: sh xyz\r\n from: second/path\r\n\r\n\r\n\r\nFlat Loops\r\n~~~~~~~~~~\r\nLoops can also flatten itself. If you want to repeat arrays you can use the keyword ``xyml.content`` to provide the content of the loop.\r\n\r\n**Example**::\r\n\r\n array_1:\r\n - abc\r\n - xyz\r\n commands:\r\n xyml.for: iterator:array_1\r\n xyml.content:\r\n - cmd: sh {{ iterator }}\r\n - cmd: echo {{ iterator }}\r\n\r\nWill result in::\r\n\r\n array_1:\r\n - abc\r\n - xyz\r\n commands:\r\n - cmd: sh abc\r\n - cmd: echo abc\r\n - cmd: sh xyz\r\n - cmd: echo xyz\r\n\r\n\r\nLoops for Permutation\r\n~~~~~~~~~~~~~~~~~~~~~\r\n\r\nLoops can also be used to create permutations. To simplify that a loop statement can take a custom amount of iterators.\r\n\r\n**Example**::\r\n\r\n array_1:\r\n - abc\r\n - xyz\r\n array_2:\r\n - 123\r\n - 456\r\n commands:\r\n xyml.for: i:array_1, j:array_2\r\n xyml.content:\r\n - cmd: sh {{ i }} {{ j }}\r\n\r\nWill result in::\r\n\r\n array_1:\r\n - abc\r\n - xyz\r\n array_2:\r\n - 123\r\n - 456\r\n commands:\r\n - cmd: sh abc 123\r\n - cmd: sh abc 456\r\n - cmd: sh xyz 123\r\n - cmd: sh xyz 456\r\n\r\nInline Loops\r\n~~~~~~~~~~~~~~~~~~~~~\r\n\r\nYou can also use loops to improve the string values in your configuration.\r\nThis can be used to simplify reoccurring values like parameters.\r\n\r\n**Example**::\r\n\r\n array_1:\r\n - abc\r\n - xyz\r\n command: Input parameters: {{xyml.for:param:array_1:-i {{param}}}}\r\n\r\nWill result in::\r\n\r\n array_1:\r\n - abc\r\n - xyz\r\n command: Input parameters: -i abc -i xyz\r\n",
"bugtrack_url": null,
"license": "BSD 3-Clause License Copyright (c) 2023, Simon Gallitscher All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \"AS IS\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. ",
"summary": "Extends the common .yaml syntax to provide more complex configuration options",
"version": "0.3.2",
"project_urls": {
"homepage": "https://github.com/AdunSG/yaml-extender"
},
"split_keywords": [
"yaml",
" configuration",
" extension"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "fd19cb17ad6aa32c371c8762508633b2f094877c7847fc9dca140ffe0adb54f8",
"md5": "720216dddae9b7e75ad0d9cbf4922b87",
"sha256": "59741349603ffa40f1f49a7c24a162e9d05e75ec1f61fc77e0bda4fb2772f90d"
},
"downloads": -1,
"filename": "yaml_extender-0.3.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "720216dddae9b7e75ad0d9cbf4922b87",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 16690,
"upload_time": "2024-04-09T17:25:26",
"upload_time_iso_8601": "2024-04-09T17:25:26.723179Z",
"url": "https://files.pythonhosted.org/packages/fd/19/cb17ad6aa32c371c8762508633b2f094877c7847fc9dca140ffe0adb54f8/yaml_extender-0.3.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "bd895a1059c75254aba9571c23c6779215ede1f7b1e7bab7e405d047e30a7659",
"md5": "acb28b41385beb27325135ce59fdc1f3",
"sha256": "94553368d95dd55c9e25ea8e4e1aa0976d2de05e8dd4fb6b2e7b75a8b261816e"
},
"downloads": -1,
"filename": "yaml-extender-0.3.2.tar.gz",
"has_sig": false,
"md5_digest": "acb28b41385beb27325135ce59fdc1f3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 18631,
"upload_time": "2024-04-09T17:25:28",
"upload_time_iso_8601": "2024-04-09T17:25:28.240698Z",
"url": "https://files.pythonhosted.org/packages/bd/89/5a1059c75254aba9571c23c6779215ede1f7b1e7bab7e405d047e30a7659/yaml-extender-0.3.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-09 17:25:28",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "AdunSG",
"github_project": "yaml-extender",
"travis_ci": false,
"coveralls": true,
"github_actions": false,
"lcname": "yaml-extender"
}
