From c9434fa95fafeb1f191d5f25cc2cf227b250174b Mon Sep 17 00:00:00 2001 From: Sandra McCann Date: Thu, 3 Dec 2020 01:03:43 -0500 Subject: [PATCH] [1/2]docs copyedit for the ansible.utils collection (#26) [1/2]docs copyedit for the ansible.utils collection Reviewed-by: https://github.com/apps/ansible-zuul --- README.md | 25 ++++++++------ changelogs/fragments/docs_copyedit.yaml | 3 ++ docs/ansible.utils.fact_diff_module.rst | 20 ++++++------ docs/ansible.utils.get_path_filter.rst | 18 +++++----- docs/ansible.utils.get_path_lookup.rst | 18 +++++----- docs/ansible.utils.index_of_filter.rst | 28 ++++++++-------- docs/ansible.utils.index_of_lookup.rst | 28 ++++++++-------- docs/ansible.utils.jsonschema_validate.rst | 5 ++- docs/ansible.utils.to_paths_filter.rst | 18 +++++----- docs/ansible.utils.to_paths_lookup.rst | 22 ++++++------- docs/ansible.utils.update_fact_module.rst | 16 ++++----- docs/ansible.utils.validate_filter.rst | 18 +++++----- docs/ansible.utils.validate_lookup.rst | 18 +++++----- docs/ansible.utils.validate_module.rst | 14 ++++---- plugins/filter/get_path.py | 18 +++++----- plugins/filter/index_of.py | 28 ++++++++-------- plugins/filter/to_paths.py | 18 +++++----- plugins/filter/validate.py | 18 +++++----- plugins/lookup/get_path.py | 22 ++++++------- plugins/lookup/index_of.py | 38 +++++++++++----------- plugins/lookup/to_paths.py | 22 ++++++------- plugins/lookup/validate.py | 18 +++++----- plugins/modules/fact_diff.py | 20 ++++++------ plugins/modules/update_fact.py | 16 ++++----- plugins/modules/validate.py | 18 +++++----- 25 files changed, 247 insertions(+), 240 deletions(-) create mode 100644 changelogs/fragments/docs_copyedit.yaml diff --git a/README.md b/README.md index 5bcab75..0aa458e 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,9 @@ -# Ansible Utilities Collection +# Ansible Utilities Collection [![Codecov](https://img.shields.io/codecov/c/github/ansible-collections/ansible.utils)](https://codecov.io/gh/ansible-collections/ansible.utils) -The Ansible ``ansible.utils`` collection includes a variety of plugins that aid in the management, manupulation and visibility of data for the Ansible playbook developer. +The Ansible ``ansible.utils`` collection includes a variety of plugins that aid in the management, manipulation and visibility of data for the Ansible playbook developer. ## Ansible version compatibility @@ -22,7 +22,7 @@ PEP440 is the schema used to describe the versions of Ansible. Name | Description --- | --- [ansible.utils.get_path](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.get_path_filter.rst)|Retrieve the value in a variable using a path -[ansible.utils.index_of](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.index_of_filter.rst)|Find the indicies of items in a list matching some criteria +[ansible.utils.index_of](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.index_of_filter.rst)|Find the indices of items in a list matching some criteria [ansible.utils.to_paths](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.to_paths_filter.rst)|Flatten a complex object into a dictionary of paths and values [ansible.utils.validate](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.validate_filter.rst)|Validate data with provided criteria @@ -30,7 +30,7 @@ Name | Description Name | Description --- | --- [ansible.utils.get_path](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.get_path_lookup.rst)|Retrieve the value in a variable using a path -[ansible.utils.index_of](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.index_of_lookup.rst)|Find the indicies of items in a list matching some criteria +[ansible.utils.index_of](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.index_of_lookup.rst)|Find the indices of items in a list matching some criteria [ansible.utils.to_paths](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.to_paths_lookup.rst)|Flatten a complex object into a dictionary of paths and values [ansible.utils.validate](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.validate_lookup.rst)|Validate data with provided criteria @@ -46,6 +46,11 @@ Name | Description --- | --- [ansible.utils.validate](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.validate_test.rst)|Validate data with provided criteria +### Validate plugins +Name | Description +--- | --- +[ansible.utils.jsonschema](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.jsonschema_validate.rst)|Define configurable options for jsonschema validate plugin + ## Installing this collection @@ -63,18 +68,18 @@ collections: ``` ## Using this collection -The most common use case for this collection is when complex data structures are present in an Ansible playbook, inventory, or returned from modules are worked with. +The most common use case for this collection is when you want to work with the complex data structures present in an Ansible playbook, inventory, or returned from modules. See each plugin documentation page for detailed examples for how these utilities can be used in tasks. **NOTE**: For Ansible 2.9, you may not see deprecation warnings when you run your playbooks with this collection. Use this documentation to track when a module is deprecated. ### See Also: -* [Ansible Using collections](https://docs.ansible.com/ansible/latest/user_guide/collections_using.html) for more details. +* [Using collections](https://docs.ansible.com/ansible/latest/user_guide/collections_using.html) in the Ansible documentation for more details. ## Contributing to this collection -This collection is intended for plugins that are not platform or discipline specific. Simple plugin examples should be generic in nature, more complex examples can include real world platform module to demonstrate the utility of the plugin in a playbook. +This collection is intended for plugins that are not platform or discipline specific. Simple plugin examples should be generic in nature. More complex examples can include real world platform modules to demonstrate the utility of the plugin in a playbook. We welcome community contributions to this collection. If you find problems, please open an issue or create a PR against the [ansible.utils collection repository](https://github.com/ansible-collections/ansible.utils). See [Contributing to Ansible-maintained collections](https://docs.ansible.com/ansible/devel/community/contributing_maintained_collections.html#contributing-maintained-collections) for complete details. @@ -83,11 +88,11 @@ See the [Ansible Community Guide](https://docs.ansible.com/ansible/latest/commun ### Developer notes - 100% code coverage is the goal, although it's not always possible. Please include unit and integration tests with all PRs. PRs should not cause a decrease in code coverage. -- filter plugins should be 1 per file, with an included DOCUMENTATION string/or reference a lookup plugin with the same name. -- action, filter and lookup plugins should use argspec validation, see AnsibleArgSpecValidator +- Filter plugins should be 1 per file, with an included DOCUMENTATION string, or reference a lookup plugin with the same name. +- Action, filter, and lookup plugins should use argspec validation. See [AnsibleArgSpecValidator](https://github.com/ansible-collections/ansible.utils/blob/main/plugins/module_utils/common/argspec_validate.py). - This collection should not depend on other collections for imported code - Use of the latest version of black is required for formatting (black -l79) -- The README contains a table of plugins, the collection_prep utilities make this easy to maintain +- The README contains a table of plugins. Use the [collection_prep](https://github.com/ansible-network/collection_prep) utilities to maintain this. ### Code of Conduct diff --git a/changelogs/fragments/docs_copyedit.yaml b/changelogs/fragments/docs_copyedit.yaml new file mode 100644 index 0000000..14fec47 --- /dev/null +++ b/changelogs/fragments/docs_copyedit.yaml @@ -0,0 +1,3 @@ +--- +trivial: + - Edited the documentation diff --git a/docs/ansible.utils.fact_diff_module.rst b/docs/ansible.utils.fact_diff_module.rst index e727124..263fe70 100644 --- a/docs/ansible.utils.fact_diff_module.rst +++ b/docs/ansible.utils.fact_diff_module.rst @@ -17,7 +17,7 @@ Version added: 1.0.0 Synopsis -------- -- Compare two facts or variables and get a diff +- Compare two facts or variables and get a diff. @@ -46,7 +46,7 @@ Parameters -
The second fact to be used in the comparison
+
The second fact to be used in the comparison.
@@ -62,7 +62,7 @@ Parameters -
The first fact to be used in the comparison
+
The first fact to be used in the comparison.
@@ -95,7 +95,7 @@ Parameters Default:
"ansible.utils.native"
-
The diff plugin to use, in collection format
+
The diff plugin to use, in fully qualified collection name format.
@@ -112,7 +112,7 @@ Parameters Default:
{}
-
Parameters passed to the diff plugin
+
Parameters passed to the diff plugin.
@@ -129,9 +129,9 @@ Parameters -
Skip lines matching these regular expressions
-
Matches will be removed prior to the diff
-
If the provided before and after are a string, they will be split
+
Skip lines matching these regular expressions.
+
Matches will be removed prior to the diff.
+
If the provided before and after are a string, they will be split.
Each entry in each list will be cast to a string for the comparison
@@ -302,7 +302,7 @@ Common return values are documented `here always -
The diff_text split into lines
+
The diff_text split into lines.

@@ -317,7 +317,7 @@ Common return values are documented `here always -
The diff in text format
+
The diff in text format.

diff --git a/docs/ansible.utils.get_path_filter.rst b/docs/ansible.utils.get_path_filter.rst index b7ae2f5..0bbfe55 100644 --- a/docs/ansible.utils.get_path_filter.rst +++ b/docs/ansible.utils.get_path_filter.rst @@ -8,7 +8,7 @@ ansible.utils.get_path **Retrieve the value in a variable using a path** -Version added: 1.0 +Version added: 1.0.0 .. contents:: :local: @@ -17,8 +17,8 @@ Version added: 1.0 Synopsis -------- -- Use a ``path`` to retreive a nested value from a ``var`` -- ``get_path`` is also available as a ``lookup plugin`` for convenience +- Use a ``path`` to retrieve a nested value from a ``var``. +- ``get_path`` is also available as a ``lookup plugin`` for convenience. - Using the parameters below- ``var|ansible.utils.get_path(path, wantlist``) @@ -52,7 +52,7 @@ Parameters
The path in the var to retrieve the value of.
-
The path needs to a be a valid jinja path
+
The path needs to be a valid jinja path.
@@ -70,8 +70,8 @@ Parameters -
The variable from which the value should be extraced
-
This option represents the value that is passed to filter plugin in pipe format.
+
The variable from which the value should be extracted.
+
This option represents the value that is passed to the filter plugin in pipe format.
For example config_data|ansible.utils.get_path(), in this case config_data represents this option.
@@ -93,7 +93,7 @@ Parameters -
If set to True, the return value will always be a list
+
If set to True, the return value will always be a list.
@@ -168,8 +168,8 @@ Examples # paths: # a.b.c.d[0]: 0 # a.b.c.d[1]: 1 - # a.b.c.e[0]: true - # a.b.c.e[1]: false + # a.b.c.e[0]: True + # a.b.c.e[1]: False # TASK [Retrieve the value of each path from vars] ****************** # ok: [nxos101] => (item=a.b.c.d[0]) => diff --git a/docs/ansible.utils.get_path_lookup.rst b/docs/ansible.utils.get_path_lookup.rst index 11aa0d6..ec39727 100644 --- a/docs/ansible.utils.get_path_lookup.rst +++ b/docs/ansible.utils.get_path_lookup.rst @@ -8,7 +8,7 @@ ansible.utils.get_path **Retrieve the value in a variable using a path** -Version added: 1.0 +Version added: 1.0.0 .. contents:: :local: @@ -17,7 +17,7 @@ Version added: 1.0 Synopsis -------- -- Use a ``path`` to retreive a nested value from a ``var`` +- Use a ``path`` to retrieve a nested value from a ``var`` - ``get_path`` is also available as a ``filter plugin`` for convenience - Using the parameters below- ``lookup('ansible.utils.get_path', var, path, wantlist``) @@ -51,7 +51,7 @@ Parameters -
The path in the var to retrieve the value of. The path needs to a be a valid jinja path
+
The path in the var to retrieve the value of. The path needs to a be a valid jinja path.
@@ -69,7 +69,7 @@ Parameters -
The variable from which the value should be extraced
+
The variable from which the value should be extracted.
@@ -90,7 +90,7 @@ Parameters -
If set to True, the return value will always be a list This can also be accomplished using query or q instead of lookup https://docs.ansible.com/ansible/latest/plugins/lookup.html
+
If set to True, the return value will always be a list. This can also be accomplished using query or q instead of lookup. https://docs.ansible.com/ansible/latest/plugins/lookup.html.
@@ -165,8 +165,8 @@ Examples # paths: # a.b.c.d[0]: 0 # a.b.c.d[1]: 1 - # a.b.c.e[0]: true - # a.b.c.e[1]: false + # a.b.c.e[0]: True + # a.b.c.e[1]: False # TASK [Retrieve the value of each path from vars] ****************** # ok: [nxos101] => (item=a.b.c.d[0]) => @@ -231,8 +231,8 @@ Common return values are documented `here -
One or more zero-based indicies of the matching list items
-
See wantlist if a list is always required
+
One or more zero-based indices of the matching list items.
+
See wantlist if a list is always required.

diff --git a/docs/ansible.utils.index_of_filter.rst b/docs/ansible.utils.index_of_filter.rst index d9900d7..ea97ebf 100644 --- a/docs/ansible.utils.index_of_filter.rst +++ b/docs/ansible.utils.index_of_filter.rst @@ -5,10 +5,10 @@ ansible.utils.index_of ********************** -**Find the indicies of items in a list matching some criteria** +**Find the indices of items in a list matching some criteria** -Version added: 1.0 +Version added: 1.0.0 .. contents:: :local: @@ -17,9 +17,9 @@ Version added: 1.0 Synopsis -------- -- This plugin returns the indicies of items matching some criteria in a list -- When working with a list of dictionaries, the key to evaluate can be specified -- ``index_of`` is also available as a ``lookup plugin`` for convenience +- This plugin returns the indices of items matching some criteria in a list. +- When working with a list of dictionaries, the key to evaluate can be specified. +- ``index_of`` is also available as a ``lookup plugin`` for convenience. - Using the parameters below- ``data|ansible.utils.index_of(test, value, key, fail_on_missing, wantlist``) @@ -52,8 +52,8 @@ Parameters -
A list of items to enumerate and test against
-
This option represents the value that is passed to filter plugin in pipe format.
+
A list of items to enumerate and test against.
+
This option represents the value that is passed to the filter plugin in pipe format.
For example config_data|ansible.utils.index_of('x'), in this case config_data represents this option.
@@ -75,7 +75,7 @@ Parameters -
When provided a list of dictionaries, fail if the key is missing from one or more of the dictionaries
+
When provided a list of dictionaries, fail if the key is missing from one or more of the dictionaries.
@@ -92,9 +92,9 @@ Parameters -
When the data provided is a list of dictionaries, run the test againt this dictionary key
-
When using a key, the data must only contain dictionaries
-
See fail_on_missing below to determine the behaviour when the key is missing from a dictionary in the data
+
When the data provided is a list of dictionaries, run the test against this dictionary key.
+
When using a key, the data must only contain dictionaries.
+
See fail_on_missing below to determine the behavior when the key is missing from a dictionary in the data.
@@ -131,7 +131,7 @@ Parameters -
The value used to test each list item against
+
The value used to test each list item against.
{'Not required for simple tests (eg': 'true, false, even, odd)'}
May be a string, boolean, number, regular expesion dict etc, depending on the test used
@@ -154,8 +154,8 @@ Parameters -
When only a single entry in the data is matched, that entries index is returned as an integer
-
If set to True, the return value will always be a list, even if only a single entry is matched
+
When only a single entry in the data is matched, the index of that entry is returned as an integer.
+
If set to True, the return value will always be a list, even if only a single entry is matched.
diff --git a/docs/ansible.utils.index_of_lookup.rst b/docs/ansible.utils.index_of_lookup.rst index b9c9e55..b741203 100644 --- a/docs/ansible.utils.index_of_lookup.rst +++ b/docs/ansible.utils.index_of_lookup.rst @@ -5,10 +5,10 @@ ansible.utils.index_of ********************** -**Find the indicies of items in a list matching some criteria** +**Find the indices of items in a list matching some criteria** -Version added: 1.0 +Version added: 1.0.0 .. contents:: :local: @@ -17,10 +17,10 @@ Version added: 1.0 Synopsis -------- -- This plugin returns the indicies of items matching some criteria in a list -- When working with a list of dictionaries, the key to evaluate can be specified -- ``index_of`` is also available as a ``filter plugin`` for convenience -- Using the parameters below- ``lookup('ansible.utils.index_of', data, test, value, key, fail_on_missing, wantlist``) +- This plugin returns the indices of items matching some criteria in a list. +- When working with a list of dictionaries, the key to evaluate can be specified. +- ``index_of`` is also available as a ``filter plugin`` for convenience. +- Using the parameters below- ``lookup('ansible.utils.index_of', data, test, value, key, fail_on_missing, wantlist``). @@ -52,7 +52,7 @@ Parameters -
A list of items to enumerate and test against
+
A list of items to enumerate and test against.
@@ -73,7 +73,7 @@ Parameters -
When provided a list of dictionaries, fail if the key is missing from one or more of the dictionaries
+
When provided a list of dictionaries, fail if the key is missing from one or more of the dictionaries.
@@ -90,7 +90,7 @@ Parameters -
When the data provided is a list of dictionaries, run the test againt this dictionary key When using a key, the data must only contain dictionaries See fail_on_missing below to determine the behaviour when the key is missing from a dictionary in the data
+
When the data provided is a list of dictionaries, run the test against this dictionary key. When using a key, the data must only contain dictionaries. See fail_on_missing below to determine the behaviour when the key is missing from a dictionary in the data.
@@ -108,7 +108,7 @@ Parameters -
The name of the test to run against the list, a valid jinja2 test or ansible test plugin. Jinja2 includes the following tests http://jinja.palletsprojects.com/templates/#builtin-tests. An overview of tests included in ansible https://docs.ansible.com/ansible/latest/user_guide/playbooks_tests.html
+
The name of the test to run against the list, a valid jinja2 test or ansible test plugin. Jinja2 includes the following tests http://jinja.palletsprojects.com/templates/#builtin-tests. An overview of tests included in ansible https://docs.ansible.com/ansible/latest/user_guide/playbooks_tests.html.
@@ -125,7 +125,7 @@ Parameters -
The value used to test each list item against Not required for simple tests (eg: true, false, even, odd) May be a string, boolean, number, regular expesion dict etc, depending on the test used
+
The value used to test each list item against. Not required for simple tests (eg: true, false, even, odd) May be a string, boolean, number, regular expesion dict etc, depending on the test used.
@@ -146,7 +146,7 @@ Parameters -
When only a single entry in the data is matched, that entries index is returned as an integer If set to True, the return value will always be a list, even if only a single entry is matched This can also be accomplised using query or q instead of lookup https://docs.ansible.com/ansible/latest/plugins/lookup.html
+
When only a single entry in the data is matched, the index of that entry is returned as an integer. If set to True, the return value will always be a list, even if only a single entry is matched. This can also be accomplised using query or q instead of lookup. https://docs.ansible.com/ansible/latest/plugins/lookup.html
@@ -429,8 +429,8 @@ Common return values are documented `here -
One or more zero-based indicies of the matching list items
-
See wantlist if a list is always required
+
One or more zero-based indicies of the matching list items.
+
See wantlist if a list is always required.

diff --git a/docs/ansible.utils.jsonschema_validate.rst b/docs/ansible.utils.jsonschema_validate.rst index d55620f..c3ab581 100644 --- a/docs/ansible.utils.jsonschema_validate.rst +++ b/docs/ansible.utils.jsonschema_validate.rst @@ -5,7 +5,7 @@ ansible.utils.jsonschema ************************ -**Define configurable options for jsonschema validate sub-plugin (engine).** +**Define configurable options for jsonschema validate plugin** Version added: 1.0.0 @@ -17,7 +17,7 @@ Version added: 1.0.0 Synopsis -------- -- This plugin documentation provides the configurable options when *ansible.utils.jsonschema* is used as a value for ``engine`` option within ``validate`` plugins. Refer individual ``validate`` plugin docs ``engine`` option for more details. +- This plugin documentation provides the configurable options that can be passed to the validate plugins when *ansible.utils.json* is used as a value for engine option. @@ -67,7 +67,6 @@ Notes ----- .. note:: - - This sub-plugin is not a standalone pluign and works only when used with ``validate`` plugins. This plugin will be used when ``engine`` option of ``validate`` plugin is set to *ansible.utils.jsonschema*. - The value of ``data`` option should be either of type *dict* or *strings* which should be a valid *dict* when read in python. - The value of ``criteria`` should be *list* of *dict* or *list* of *strings* and each *string* within the *list* entry should be a valid *dict* when read in python. diff --git a/docs/ansible.utils.to_paths_filter.rst b/docs/ansible.utils.to_paths_filter.rst index e071222..d573443 100644 --- a/docs/ansible.utils.to_paths_filter.rst +++ b/docs/ansible.utils.to_paths_filter.rst @@ -8,7 +8,7 @@ ansible.utils.to_paths **Flatten a complex object into a dictionary of paths and values** -Version added: 1.0 +Version added: 1.0.0 .. contents:: :local: @@ -18,9 +18,9 @@ Version added: 1.0 Synopsis -------- - Flatten a complex object into a dictionary of paths and values. -- Paths are dot delimited whenever possible -- Brakets are used for list indicies and keys that contain special characters -- ``to_paths`` is also available as a ``lookup plugin`` for convenience +- Paths are dot delimited whenever possible. +- Brakets are used for list indices and keys that contain special characters. +- ``to_paths`` is also available as a ``lookup plugin`` for convenience. - Using the parameters below- ``var|ansible.utils.to_paths(prepend, wantlist``) @@ -71,7 +71,7 @@ Parameters
The value of var will be will be used.
-
This option represents the value that is passed to filter plugin in pipe format.
+
This option represents the value that is passed to the filter plugin in pipe format.
For example config_data|ansible.utils.to_paths(), in this case config_data represents this option.
@@ -129,8 +129,8 @@ Examples # paths: # b.c.d[0]: 0 # b.c.d[1]: 1 - # b.c.e[0]: true - # b.c.e[1]: false + # b.c.e[0]: True + # b.c.e[1]: False - name: Use prepend to add the initial variable name ansible.builtin.set_fact: @@ -142,8 +142,8 @@ Examples # paths: # a.b.c.d[0]: 0 # a.b.c.d[1]: 1 - # a.b.c.e[0]: true - # a.b.c.e[1]: false + # a.b.c.e[0]: True + # a.b.c.e[1]: False #### Using a complex object diff --git a/docs/ansible.utils.to_paths_lookup.rst b/docs/ansible.utils.to_paths_lookup.rst index 941ee63..a8ae00f 100644 --- a/docs/ansible.utils.to_paths_lookup.rst +++ b/docs/ansible.utils.to_paths_lookup.rst @@ -8,7 +8,7 @@ ansible.utils.to_paths **Flatten a complex object into a dictionary of paths and values** -Version added: 1.0 +Version added: 1.0.0 .. contents:: :local: @@ -18,9 +18,9 @@ Version added: 1.0 Synopsis -------- - Flatten a complex object into a dictionary of paths and values. -- Paths are dot delimited whenever possible -- Brakets are used for list indicies and keys that contain special characters -- ``to_paths`` is also available as a filter plugin +- Paths are dot delimited whenever possible. +- Brackets are used for list indices and keys that contain special characters. +- ``to_paths`` is also available as a filter plugin. - Using the parameters below- ``lookup('ansible.utils.to_paths', var, prepend, wantlist``) @@ -127,8 +127,8 @@ Examples # paths: # b.c.d[0]: 0 # b.c.d[1]: 1 - # b.c.e[0]: true - # b.c.e[1]: false + # b.c.e[0]: True + # b.c.e[1]: False - name: Use prepend to add the initial variable name ansible.builtin.set_fact: @@ -140,8 +140,8 @@ Examples # paths: # a.b.c.d[0]: 0 # a.b.c.d[1]: 1 - # a.b.c.e[0]: true - # a.b.c.e[1]: false + # a.b.c.e[0]: True + # a.b.c.e[1]: False #### Using a complex object @@ -201,9 +201,9 @@ Common return values are documented `here -
A dictionary of key value pairs
-
The key is the path
-
The value is the value
+
A dictionary of key value pairs.
+
The key is the path.
+
The value is the value.

diff --git a/docs/ansible.utils.update_fact_module.rst b/docs/ansible.utils.update_fact_module.rst index 895e898..5d2cd78 100644 --- a/docs/ansible.utils.update_fact_module.rst +++ b/docs/ansible.utils.update_fact_module.rst @@ -19,7 +19,7 @@ Synopsis -------- - This module allows updating existing variables. - Variables are updated on a host-by-host basis. -- Variable are not modified in place, instead they are returned by the module +- Variables are not modified in place, instead they are returned by the module. @@ -49,7 +49,7 @@ Parameters -
A list of dictionaries, each a desired update to make
+
A list of dictionaries, each a desired update to make.
@@ -66,9 +66,9 @@ Parameters -
The path in a currently set variable to update
-
The path can be in dot or bracket notation
-
It should be a valid jinja reference
+
The path in a currently set variable to update.
+
The path can be in dot or bracket notation.
+
It should be a valid jinja reference.
@@ -85,8 +85,8 @@ Parameters -
The value to be set at the path
-
Can be a simple or complex data structure
+
The value to be set at the path.
+
Can be a simple or complex data structure.
@@ -296,7 +296,7 @@ Examples state: gathered register: current - - name: Update the source of sequenmce 10 in the IPv4 ACL named test1 + - name: Update the source of sequence 10 in the IPv4 ACL named test1 ansible.utils.update_fact: updates: - path: current.gathered[{{ afi }}].acls[{{ acl }}].aces[{{ ace }}].source diff --git a/docs/ansible.utils.validate_filter.rst b/docs/ansible.utils.validate_filter.rst index bafc772..566d916 100644 --- a/docs/ansible.utils.validate_filter.rst +++ b/docs/ansible.utils.validate_filter.rst @@ -50,8 +50,8 @@ Parameters
The criteria used for validation of value that represents data options.
-
This option represents the first argument passed in the filter plugin For example config_data|ansible.utils.validate(config_criteria), in this case the value of config_criteria represents this option.
-
For the type of criteria that represents this value refer documentation of individual validator plugins.
+
This option represents the first argument passed in the filter plugin. For example config_data|ansible.utils.validate(config_criteria), in this case the value of config_criteria represents this option.
+
For the type of criteria that represents this value refer to the documentation of individual validator plugins.
@@ -69,9 +69,9 @@ Parameters -
A data that will be validated against criteria.
-
This option represents the value that is passed to filter plugin in pipe format. For example config_data|ansible.utils.validate(), in this case config_data represents this option.
-
For the type of data that represents this value refer documentation of individual validator plugins.
+
Data that will be validated against criteria.
+
This option represents the value that is passed to the filter plugin in pipe format. For example config_data|ansible.utils.validate(), in this case config_data represents this option.
+
For the type of data that represents this value refer to the documentation of individual validator plugins.
@@ -90,7 +90,7 @@ Parameters
The name of the validator plugin to use.
-
This option can be passed in lookup plugin as a key, value pair For example config_data|ansible.utils.validate(config_criteria, engine='ansible.utils.jsonschema'), in this case the value ansible.utils.jsonschema represents the engine to be use for data valdiation. If the value is not provided the default value that is ansible.uitls.jsonschema will be used.
+
This option can be passed in lookup plugin as a key, value pair. For example config_data|ansible.utils.validate(config_criteria, engine='ansible.utils.jsonschema'), in this case the value ansible.utils.jsonschema represents the engine to be use for data valdiation. If the value is not provided the default value that is ansible.uitls.jsonschema will be used.
The value should be in fully qualified collection name format that is <org-name>.<collection-name>.<validator-plugin-name>.
@@ -102,8 +102,8 @@ Notes ----- .. note:: - - For the type of options ``data`` and ``criteria`` refer the individual ``validate`` plugin documentation that is represented in the value of ``engine`` option. - - For additional plugin configuration options refer the individual ``validate`` plugin documentation that is represented by the value of ``engine`` option. + - For the type of options ``data`` and ``criteria`` refer to the individual ``validate`` plugin documentation that is represented in the value of ``engine`` option. + - For additional plugin configuration options refer to the individual ``validate`` plugin documentation that is represented by the value of ``engine`` option. - The plugin configuration option can be either passed as *key=value* pairs within filter plugin or environment variables. - The precedence of the ``validate`` plugin configurable option is the variable passed within filter plugin as *key=value* pairs followed by the environment variables. @@ -119,7 +119,7 @@ Examples data: "{{ lookup('file', './validate/data/show_interfaces_iosxr.json')}}" criteria: "{{ lookup('file', './validate/criteria/jsonschema/show_interfaces_iosxr.json')}}" - - name: validate data in json format using jsonschema with by passing plugin configuration variable as key/value pairs + - name: validate data in json format using jsonschema by passing plugin configuration variable as key/value pairs ansible.builtin.set_fact: data_validilty: "{{ data|ansible.utils.validate(criteria, engine='ansible.utils.jsonschema', draft='draft7') }}" diff --git a/docs/ansible.utils.validate_lookup.rst b/docs/ansible.utils.validate_lookup.rst index 4e468a7..ff4293d 100644 --- a/docs/ansible.utils.validate_lookup.rst +++ b/docs/ansible.utils.validate_lookup.rst @@ -51,7 +51,7 @@ Parameters
The criteria used for validation of value that represents data options.
This option represents the second argument passed in the lookup plugin For example lookup(config_data, config_criteria, engine='ansible.utils.jsonschema'), in this case the value of config_criteria represents this option.
-
For the type of criteria that represents this value refer documentation of individual validate plugins.
+
For the type of criteria that represents this value refer to the documentation of individual validate plugins.
@@ -69,9 +69,9 @@ Parameters -
A data that will be validated against criteria.
-
This option represents the value that is passed to lookup plugin as first argument. For example lookup(config_data, config_criteria, engine='ansible.utils.jsonschema'), in this case config_data represents this option.
-
For the type of data that represents this value refer documentation of individual validate plugins.
+
Data that will be validated against criteria.
+
This option represents the value that is passed to the lookup plugin as the first argument. For example lookup(config_data, config_criteria, engine='ansible.utils.jsonschema'), in this case config_data represents this option.
+
For the type of data that represents this value refer to the documentation of individual validate plugins.
@@ -90,7 +90,7 @@ Parameters
The name of the validate plugin to use.
-
This option can be passed in lookup plugin as a key, value pair For example lookup(config_data, config_criteria, engine='ansible.utils.jsonschema'), in this case the value ansible.utils.jsonschema represents the engine to be use for data valdiation. If the value is not provided the default value that is ansible.uitls.jsonschema will be used.
+
This option can be passed in lookup plugin as a key, value pair. For example lookup(config_data, config_criteria, engine='ansible.utils.jsonschema'), in this case the value ansible.utils.jsonschema represents the engine to be use for data valdiation. If the value is not provided the default value that is ansible.uitls.jsonschema will be used.
The value should be in fully qualified collection name format that is <org-name>.<collection-name>.<validate-plugin-name>.
@@ -102,8 +102,8 @@ Notes ----- .. note:: - - For the type of options ``data`` and ``criteria`` refer the individual ``validate`` plugin documentation that is represented in the value of ``engine`` option. - - For additional plugin configuration options refer the individual ``validate`` plugin documentation that is represented by the value of ``engine`` option. + - For the type of options ``data`` and ``criteria`` refer to the individual ``validate`` plugin documentation that is represented in the value of ``engine`` option. + - For additional plugin configuration options refer to the individual ``validate`` plugin documentation that is represented by the value of ``engine`` option. - The plugin configuration option can be either passed as *key=value* pairs within lookup plugin or task or environment variables. - The precedence the ``validate`` plugin configurable option is the variable passed within lookup plugin as *key=value* pairs followed by task variables followed by environment variables. @@ -154,8 +154,8 @@ Common return values are documented `here -
If data is valid returns empty list
-
If data is invalid returns list of errors in data
+
If data is valid returns empty list.
+
If data is invalid returns list of errors in data.

diff --git a/docs/ansible.utils.validate_module.rst b/docs/ansible.utils.validate_module.rst index cf9546b..64cdb4b 100644 --- a/docs/ansible.utils.validate_module.rst +++ b/docs/ansible.utils.validate_module.rst @@ -46,7 +46,7 @@ Parameters -
The criteria used for validation of data. For the type of criteria refer documentation of individual validate plugins.
+
The criteria used for validation of data. For the type of criteria refer to the documentation of individual validate plugins.
@@ -62,7 +62,7 @@ Parameters -
A data that will be validated against criteria. For the type of data refer documentation of individual validate plugins
+
Data that will be validated against criteria. For the type of data refer to the documentation of individual validate plugins.
@@ -78,7 +78,7 @@ Parameters Default:
"ansible.utils.jsonschema"
-
The name of the validate plugin to use. The engine value should follow the fully qualified collection name format that is <org-name>.<collection-name>.<validate-plugin-name>.
+
The name of the validate plugin to use. The engine value should follow the fully qualified collection name format, that is <org-name>.<collection-name>.<validate-plugin-name>.
@@ -89,10 +89,10 @@ Notes ----- .. note:: - - For the type of options ``data`` and ``criteria`` refer the individual ``validate`` plugin documentation that is represented in the value of ``engine`` option. - - For additional plugin configuration options refer the individual ``validate`` plugin documentation that is represented by the value of ``engine`` option. + - For the type of options ``data`` and ``criteria`` refer to the individual ``validate`` plugin documentation that is represented in the value of ``engine`` option. + - For additional plugin configuration options refer to the individual ``validate`` plugin documentation that is represented by the value of ``engine`` option. - The plugin configuration option can be either passed as task or environment variables. - - The precedence the ``validate`` plugin configurable option is task variables followed by the environment variables. + - The precedence of the ``validate`` plugin configurable option is task variables followed by the environment variables. @@ -155,7 +155,7 @@ Common return values are documented `here always
The msg indicates if the data is valid as per the criteria.
-
In case data is valid return success message all checks passed
+
In case data is valid return success message all checks passed.
In case data is invalid return error message Validation errors were found along with more information on error is available.

diff --git a/plugins/filter/get_path.py b/plugins/filter/get_path.py index 6fd05a4..d648089 100644 --- a/plugins/filter/get_path.py +++ b/plugins/filter/get_path.py @@ -14,29 +14,29 @@ __metaclass__ = type DOCUMENTATION = """ filter: get_path author: Bradley Thornton (@cidrblock) - version_added: "1.0" + version_added: "1.0.0" short_description: Retrieve the value in a variable using a path description: - - Use a C(path) to retreive a nested value from a C(var) - - C(get_path) is also available as a C(lookup plugin) for convenience + - Use a C(path) to retrieve a nested value from a C(var). + - C(get_path) is also available as a C(lookup plugin) for convenience. - Using the parameters below- C(var|ansible.utils.get_path(path, wantlist)) options: var: description: - - The variable from which the value should be extraced - - This option represents the value that is passed to filter plugin in pipe format. + - The variable from which the value should be extracted. + - This option represents the value that is passed to the filter plugin in pipe format. - For example I(config_data|ansible.utils.get_path()), in this case I(config_data) represents this option. type: raw required: True path: description: - The C(path) in the C(var) to retrieve the value of. - - The C(path) needs to a be a valid jinja path + - The C(path) needs to be a valid jinja path. type: str required: True wantlist: description: - - If set to C(True), the return value will always be a list + - If set to C(True), the return value will always be a list. type: bool notes: @@ -104,8 +104,8 @@ EXAMPLES = r""" # paths: # a.b.c.d[0]: 0 # a.b.c.d[1]: 1 -# a.b.c.e[0]: true -# a.b.c.e[1]: false +# a.b.c.e[0]: True +# a.b.c.e[1]: False # TASK [Retrieve the value of each path from vars] ****************** # ok: [nxos101] => (item=a.b.c.d[0]) => diff --git a/plugins/filter/index_of.py b/plugins/filter/index_of.py index b8bc93b..b5d4c5a 100644 --- a/plugins/filter/index_of.py +++ b/plugins/filter/index_of.py @@ -14,18 +14,18 @@ __metaclass__ = type DOCUMENTATION = """ filter: index_of author: Bradley Thornton (@cidrblock) - version_added: "1.0" - short_description: Find the indicies of items in a list matching some criteria + version_added: "1.0.0" + short_description: Find the indices of items in a list matching some criteria description: - - This plugin returns the indicies of items matching some criteria in a list - - When working with a list of dictionaries, the key to evaluate can be specified - - C(index_of) is also available as a C(lookup plugin) for convenience + - This plugin returns the indices of items matching some criteria in a list. + - When working with a list of dictionaries, the key to evaluate can be specified. + - C(index_of) is also available as a C(lookup plugin) for convenience. - Using the parameters below- C(data|ansible.utils.index_of(test, value, key, fail_on_missing, wantlist)) options: data: description: - - A list of items to enumerate and test against - - This option represents the value that is passed to filter plugin in pipe format. + - A list of items to enumerate and test against. + - This option represents the value that is passed to the filter plugin in pipe format. - For example I(config_data|ansible.utils.index_of('x')), in this case I(config_data) represents this option. type: list required: True @@ -38,23 +38,23 @@ DOCUMENTATION = """ required: True value: description: - - The value used to test each list item against + - The value used to test each list item against. - Not required for simple tests (eg: C(true), C(false), C(even), C(odd)) - May be a C(string), C(boolean), C(number), C(regular expesion) C(dict) etc, depending on the C(test) used type: raw key: description: - - When the data provided is a list of dictionaries, run the test againt this dictionary key - - When using a C(key), the C(data) must only contain dictionaries - - See C(fail_on_missing) below to determine the behaviour when the C(key) is missing from a dictionary in the C(data) + - When the data provided is a list of dictionaries, run the test against this dictionary key. + - When using a C(key), the C(data) must only contain dictionaries. + - See C(fail_on_missing) below to determine the behavior when the C(key) is missing from a dictionary in the C(data). type: str fail_on_missing: - description: When provided a list of dictionaries, fail if the key is missing from one or more of the dictionaries + description: When provided a list of dictionaries, fail if the key is missing from one or more of the dictionaries. type: bool wantlist: description: - - When only a single entry in the C(data) is matched, that entries index is returned as an integer - - If set to C(True), the return value will always be a list, even if only a single entry is matched + - When only a single entry in the C(data) is matched, the index of that entry is returned as an integer. + - If set to C(True), the return value will always be a list, even if only a single entry is matched. type: bool notes: diff --git a/plugins/filter/to_paths.py b/plugins/filter/to_paths.py index 06cd667..7829b48 100644 --- a/plugins/filter/to_paths.py +++ b/plugins/filter/to_paths.py @@ -15,19 +15,19 @@ __metaclass__ = type DOCUMENTATION = """ filter: to_paths author: Bradley Thornton (@cidrblock) - version_added: "1.0" + version_added: "1.0.0" short_description: Flatten a complex object into a dictionary of paths and values description: - Flatten a complex object into a dictionary of paths and values. - - Paths are dot delimited whenever possible - - Brakets are used for list indicies and keys that contain special characters - - C(to_paths) is also available as a C(lookup plugin) for convenience + - Paths are dot delimited whenever possible. + - Brakets are used for list indices and keys that contain special characters. + - C(to_paths) is also available as a C(lookup plugin) for convenience. - Using the parameters below- C(var|ansible.utils.to_paths(prepend, wantlist)) options: var: description: - The value of C(var) will be will be used. - - This option represents the value that is passed to filter plugin in pipe format. + - This option represents the value that is passed to the filter plugin in pipe format. - For example I(config_data|ansible.utils.to_paths()), in this case I(config_data) represents this option. type: raw required: True @@ -67,8 +67,8 @@ EXAMPLES = r""" # paths: # b.c.d[0]: 0 # b.c.d[1]: 1 -# b.c.e[0]: true -# b.c.e[1]: false +# b.c.e[0]: True +# b.c.e[1]: False - name: Use prepend to add the initial variable name ansible.builtin.set_fact: @@ -80,8 +80,8 @@ EXAMPLES = r""" # paths: # a.b.c.d[0]: 0 # a.b.c.d[1]: 1 -# a.b.c.e[0]: true -# a.b.c.e[1]: false +# a.b.c.e[0]: True +# a.b.c.e[1]: False #### Using a complex object diff --git a/plugins/filter/validate.py b/plugins/filter/validate.py index 1974d96..e919cf5 100644 --- a/plugins/filter/validate.py +++ b/plugins/filter/validate.py @@ -13,26 +13,26 @@ DOCUMENTATION = """ data: type: raw description: - - A data that will be validated against C(criteria). - - This option represents the value that is passed to filter plugin in pipe format. + - Data that will be validated against C(criteria). + - This option represents the value that is passed to the filter plugin in pipe format. For example I(config_data|ansible.utils.validate()), in this case I(config_data) represents this option. - - For the type of C(data) that represents this value refer documentation of individual validator plugins. + - For the type of C(data) that represents this value refer to the documentation of individual validator plugins. required: True criteria: type: raw description: - The criteria used for validation of value that represents C(data) options. - - This option represents the first argument passed in the filter plugin + - This option represents the first argument passed in the filter plugin. For example I(config_data|ansible.utils.validate(config_criteria)), in this case the value of I(config_criteria) represents this option. - - For the type of C(criteria) that represents this value refer documentation of individual validator plugins. + - For the type of C(criteria) that represents this value refer to the documentation of individual validator plugins. required: True engine: type: str description: - The name of the validator plugin to use. - - This option can be passed in lookup plugin as a key, value pair + - This option can be passed in lookup plugin as a key, value pair. For example I(config_data|ansible.utils.validate(config_criteria, engine='ansible.utils.jsonschema')), in this case the value I(ansible.utils.jsonschema) represents the engine to be use for data valdiation. If the value is not provided the default value that is I(ansible.uitls.jsonschema) will be used. @@ -40,9 +40,9 @@ DOCUMENTATION = """ I(..). default: ansible.utils.jsonschema notes: - - For the type of options C(data) and C(criteria) refer the individual C(validate) plugin + - For the type of options C(data) and C(criteria) refer to the individual C(validate) plugin documentation that is represented in the value of C(engine) option. - - For additional plugin configuration options refer the individual C(validate) plugin + - For additional plugin configuration options refer to the individual C(validate) plugin documentation that is represented by the value of C(engine) option. - The plugin configuration option can be either passed as I(key=value) pairs within filter plugin or environment variables. @@ -56,7 +56,7 @@ EXAMPLES = r""" data: "{{ lookup('file', './validate/data/show_interfaces_iosxr.json')}}" criteria: "{{ lookup('file', './validate/criteria/jsonschema/show_interfaces_iosxr.json')}}" -- name: validate data in json format using jsonschema with by passing plugin configuration variable as key/value pairs +- name: validate data in json format using jsonschema by passing plugin configuration variable as key/value pairs ansible.builtin.set_fact: data_validilty: "{{ data|ansible.utils.validate(criteria, engine='ansible.utils.jsonschema', draft='draft7') }}" """ diff --git a/plugins/lookup/get_path.py b/plugins/lookup/get_path.py index 0f6ba91..0536df9 100644 --- a/plugins/lookup/get_path.py +++ b/plugins/lookup/get_path.py @@ -15,28 +15,28 @@ __metaclass__ = type DOCUMENTATION = """ lookup: get_path author: Bradley Thornton (@cidrblock) - version_added: "1.0" + version_added: "1.0.0" short_description: Retrieve the value in a variable using a path description: - - Use a C(path) to retreive a nested value from a C(var) + - Use a C(path) to retrieve a nested value from a C(var) - C(get_path) is also available as a C(filter plugin) for convenience - Using the parameters below- C(lookup('ansible.utils.get_path', var, path, wantlist)) options: var: - description: The variable from which the value should be extraced + description: The variable from which the value should be extracted. type: raw required: True path: description: > The C(path) in the C(var) to retrieve the value of. - The C(path) needs to a be a valid jinja path + The C(path) needs to a be a valid jinja path. type: str required: True wantlist: description: > - If set to C(True), the return value will always be a list - This can also be accomplished using C(query) or C(q) instead of C(lookup) - U(https://docs.ansible.com/ansible/latest/plugins/lookup.html) + If set to C(True), the return value will always be a list. + This can also be accomplished using C(query) or C(q) instead of C(lookup). + U(https://docs.ansible.com/ansible/latest/plugins/lookup.html). type: bool notes: @@ -104,8 +104,8 @@ EXAMPLES = r""" # paths: # a.b.c.d[0]: 0 # a.b.c.d[1]: 1 -# a.b.c.e[0]: true -# a.b.c.e[1]: false +# a.b.c.e[0]: True +# a.b.c.e[1]: False # TASK [Retrieve the value of each path from vars] ****************** # ok: [nxos101] => (item=a.b.c.d[0]) => @@ -150,8 +150,8 @@ EXAMPLES = r""" RETURN = """ _raw: description: - - One or more zero-based indicies of the matching list items - - See C(wantlist) if a list is always required + - One or more zero-based indices of the matching list items. + - See C(wantlist) if a list is always required. """ from ansible.errors import AnsibleLookupError diff --git a/plugins/lookup/index_of.py b/plugins/lookup/index_of.py index c4bb4a7..a344f50 100644 --- a/plugins/lookup/index_of.py +++ b/plugins/lookup/index_of.py @@ -15,45 +15,45 @@ __metaclass__ = type DOCUMENTATION = """ lookup: index_of author: Bradley Thornton (@cidrblock) - version_added: "1.0" - short_description: Find the indicies of items in a list matching some criteria + version_added: "1.0.0" + short_description: Find the indices of items in a list matching some criteria description: - - This plugin returns the indicies of items matching some criteria in a list - - When working with a list of dictionaries, the key to evaluate can be specified - - C(index_of) is also available as a C(filter plugin) for convenience - - Using the parameters below- C(lookup('ansible.utils.index_of', data, test, value, key, fail_on_missing, wantlist)) + - This plugin returns the indices of items matching some criteria in a list. + - When working with a list of dictionaries, the key to evaluate can be specified. + - C(index_of) is also available as a C(filter plugin) for convenience. + - Using the parameters below- C(lookup('ansible.utils.index_of', data, test, value, key, fail_on_missing, wantlist)). options: data: - description: A list of items to enumerate and test against + description: A list of items to enumerate and test against. type: list required: True test: description: > The name of the test to run against the list, a valid jinja2 test or ansible test plugin. Jinja2 includes the following tests U(http://jinja.palletsprojects.com/templates/#builtin-tests). - An overview of tests included in ansible U(https://docs.ansible.com/ansible/latest/user_guide/playbooks_tests.html) + An overview of tests included in ansible U(https://docs.ansible.com/ansible/latest/user_guide/playbooks_tests.html). type: str required: True value: description: > - The value used to test each list item against + The value used to test each list item against. Not required for simple tests (eg: C(true), C(false), C(even), C(odd)) - May be a C(string), C(boolean), C(number), C(regular expesion) C(dict) etc, depending on the C(test) used + May be a C(string), C(boolean), C(number), C(regular expesion) C(dict) etc, depending on the C(test) used. type: raw key: description: > - When the data provided is a list of dictionaries, run the test againt this dictionary key - When using a C(key), the C(data) must only contain dictionaries - See C(fail_on_missing) below to determine the behaviour when the C(key) is missing from a dictionary in the C(data) + When the data provided is a list of dictionaries, run the test against this dictionary key. + When using a C(key), the C(data) must only contain dictionaries. + See C(fail_on_missing) below to determine the behaviour when the C(key) is missing from a dictionary in the C(data). type: str fail_on_missing: - description: When provided a list of dictionaries, fail if the key is missing from one or more of the dictionaries + description: When provided a list of dictionaries, fail if the key is missing from one or more of the dictionaries. type: bool wantlist: description: > - When only a single entry in the C(data) is matched, that entries index is returned as an integer - If set to C(True), the return value will always be a list, even if only a single entry is matched - This can also be accomplised using C(query) or C(q) instead of C(lookup) + When only a single entry in the C(data) is matched, the index of that entry is returned as an integer. + If set to C(True), the return value will always be a list, even if only a single entry is matched. + This can also be accomplised using C(query) or C(q) instead of C(lookup). U(https://docs.ansible.com/ansible/latest/plugins/lookup.html) type: bool @@ -310,8 +310,8 @@ EXAMPLES = r""" RETURN = """ _raw: description: - - One or more zero-based indicies of the matching list items - - See C(wantlist) if a list is always required + - One or more zero-based indicies of the matching list items. + - See C(wantlist) if a list is always required. """ from ansible.errors import AnsibleLookupError diff --git a/plugins/lookup/to_paths.py b/plugins/lookup/to_paths.py index ad791ea..33dbcd7 100644 --- a/plugins/lookup/to_paths.py +++ b/plugins/lookup/to_paths.py @@ -15,13 +15,13 @@ __metaclass__ = type DOCUMENTATION = """ lookup: to_paths author: Bradley Thornton (@cidrblock) - version_added: "1.0" + version_added: "1.0.0" short_description: Flatten a complex object into a dictionary of paths and values description: - Flatten a complex object into a dictionary of paths and values. - - Paths are dot delimited whenever possible - - Brakets are used for list indicies and keys that contain special characters - - C(to_paths) is also available as a filter plugin + - Paths are dot delimited whenever possible. + - Brackets are used for list indices and keys that contain special characters. + - C(to_paths) is also available as a filter plugin. - Using the parameters below- C(lookup('ansible.utils.to_paths', var, prepend, wantlist)) options: var: @@ -66,8 +66,8 @@ EXAMPLES = r""" # paths: # b.c.d[0]: 0 # b.c.d[1]: 1 -# b.c.e[0]: true -# b.c.e[1]: false +# b.c.e[0]: True +# b.c.e[1]: False - name: Use prepend to add the initial variable name ansible.builtin.set_fact: @@ -79,8 +79,8 @@ EXAMPLES = r""" # paths: # a.b.c.d[0]: 0 # a.b.c.d[1]: 1 -# a.b.c.e[0]: true -# a.b.c.e[1]: false +# a.b.c.e[0]: True +# a.b.c.e[1]: False #### Using a complex object @@ -120,9 +120,9 @@ EXAMPLES = r""" RETURN = """ _raw: description: - - A dictionary of key value pairs - - The key is the path - - The value is the value + - A dictionary of key value pairs. + - The key is the path. + - The value is the value. """ from ansible.errors import AnsibleLookupError diff --git a/plugins/lookup/validate.py b/plugins/lookup/validate.py index f60948a..1347553 100644 --- a/plugins/lookup/validate.py +++ b/plugins/lookup/validate.py @@ -18,11 +18,11 @@ DOCUMENTATION = """ data: type: raw description: - - A data that will be validated against C(criteria). - - This option represents the value that is passed to lookup plugin as first argument. + - Data that will be validated against C(criteria). + - This option represents the value that is passed to the lookup plugin as the first argument. For example I(lookup(config_data, config_criteria, engine='ansible.utils.jsonschema')), in this case I(config_data) represents this option. - - For the type of C(data) that represents this value refer documentation of individual validate plugins. + - For the type of C(data) that represents this value refer to the documentation of individual validate plugins. required: True criteria: type: raw @@ -31,14 +31,14 @@ DOCUMENTATION = """ - This option represents the second argument passed in the lookup plugin For example I(lookup(config_data, config_criteria, engine='ansible.utils.jsonschema')), in this case the value of I(config_criteria) represents this option. - - For the type of C(criteria) that represents this value refer documentation of individual + - For the type of C(criteria) that represents this value refer to the documentation of individual validate plugins. required: True engine: type: str description: - The name of the validate plugin to use. - - This option can be passed in lookup plugin as a key, value pair + - This option can be passed in lookup plugin as a key, value pair. For example I(lookup(config_data, config_criteria, engine='ansible.utils.jsonschema')), in this case the value I(ansible.utils.jsonschema) represents the engine to be use for data valdiation. If the value is not provided the default value that is I(ansible.uitls.jsonschema) will be used. @@ -46,9 +46,9 @@ DOCUMENTATION = """ I(..). default: ansible.utils.jsonschema notes: - - For the type of options C(data) and C(criteria) refer the individual C(validate) plugin + - For the type of options C(data) and C(criteria) refer to the individual C(validate) plugin documentation that is represented in the value of C(engine) option. - - For additional plugin configuration options refer the individual C(validate) plugin + - For additional plugin configuration options refer to the individual C(validate) plugin documentation that is represented by the value of C(engine) option. - The plugin configuration option can be either passed as I(key=value) pairs within lookup plugin or task or environment variables. @@ -76,8 +76,8 @@ EXAMPLES = r""" RETURN = """ _raw: description: - - If data is valid returns empty list - - If data is invalid returns list of errors in data + - If data is valid returns empty list. + - If data is invalid returns list of errors in data. """ from ansible.errors import AnsibleError, AnsibleLookupError diff --git a/plugins/modules/fact_diff.py b/plugins/modules/fact_diff.py index 0817d8e..b810772 100644 --- a/plugins/modules/fact_diff.py +++ b/plugins/modules/fact_diff.py @@ -15,16 +15,16 @@ module: fact_diff short_description: Find the difference between currently set facts version_added: "1.0.0" description: - - Compare two facts or variables and get a diff + - Compare two facts or variables and get a diff. options: before: description: - - The first fact to be used in the comparison + - The first fact to be used in the comparison. type: raw required: True after: description: - - The second fact to be used in the comparison + - The second fact to be used in the comparison. type: raw required: True plugin: @@ -35,20 +35,20 @@ options: suboptions: name: description: - - The diff plugin to use, in collection format + - The diff plugin to use, in fully qualified collection name format. default: ansible.utils.native type: str vars: description: - - Parameters passed to the diff plugin + - Parameters passed to the diff plugin. type: dict default: {} suboptions: skip_lines: description: - - Skip lines matching these regular expressions - - Matches will be removed prior to the diff - - If the provided I(before) and I(after) are a string, they will be split + - Skip lines matching these regular expressions. + - Matches will be removed prior to the diff. + - If the provided I(before) and I(after) are a string, they will be split. - Each entry in each list will be cast to a string for the comparison type: list @@ -194,11 +194,11 @@ EXAMPLES = r""" RETURN = """ diff_text: - description: The diff in text format + description: The diff in text format. returned: always type: str diff_lines: - description: The C(diff_text) split into lines + description: The C(diff_text) split into lines. returned: always type: list diff --git a/plugins/modules/update_fact.py b/plugins/modules/update_fact.py index 7f4f491..fd1214e 100644 --- a/plugins/modules/update_fact.py +++ b/plugins/modules/update_fact.py @@ -17,26 +17,26 @@ version_added: "1.0.0" description: - This module allows updating existing variables. - Variables are updated on a host-by-host basis. - - Variable are not modified in place, instead they are returned by the module + - Variables are not modified in place, instead they are returned by the module. options: updates: description: - - A list of dictionaries, each a desired update to make + - A list of dictionaries, each a desired update to make. type: list elements: dict required: True suboptions: path: description: - - The path in a currently set variable to update - - The path can be in dot or bracket notation - - It should be a valid jinja reference + - The path in a currently set variable to update. + - The path can be in dot or bracket notation. + - It should be a valid jinja reference. type: str required: True value: description: - - The value to be set at the path - - Can be a simple or complex data structure + - The value to be set at the path. + - Can be a simple or complex data structure. type: raw required: True @@ -244,7 +244,7 @@ EXAMPLES = r""" state: gathered register: current -- name: Update the source of sequenmce 10 in the IPv4 ACL named test1 +- name: Update the source of sequence 10 in the IPv4 ACL named test1 ansible.utils.update_fact: updates: - path: current.gathered[{{ afi }}].acls[{{ acl }}].aces[{{ ace }}].source diff --git a/plugins/modules/validate.py b/plugins/modules/validate.py index f3e1fc7..8c676f4 100644 --- a/plugins/modules/validate.py +++ b/plugins/modules/validate.py @@ -22,29 +22,29 @@ options: data: type: raw description: - - A data that will be validated against C(criteria). For the type of data refer - documentation of individual validate plugins + - Data that will be validated against C(criteria). For the type of data refer to the + documentation of individual validate plugins. required: True engine: type: str description: - - The name of the validate plugin to use. The engine value should follow - the fully qualified collection name format that is + - The name of the validate plugin to use. The engine value should follow + the fully qualified collection name format, that is ... default: ansible.utils.jsonschema criteria: type: raw description: - - The criteria used for validation of C(data). For the type of criteria refer + - The criteria used for validation of C(data). For the type of criteria refer to the documentation of individual validate plugins. required: True notes: -- For the type of options C(data) and C(criteria) refer the individual C(validate) plugin +- For the type of options C(data) and C(criteria) refer to the individual C(validate) plugin documentation that is represented in the value of C(engine) option. -- For additional plugin configuration options refer the individual C(validate) plugin +- For additional plugin configuration options refer to the individual C(validate) plugin documentation that is represented by the value of C(engine) option. - The plugin configuration option can be either passed as task or environment variables. -- The precedence the C(validate) plugin configurable option is task variables followed +- The precedence of the C(validate) plugin configurable option is task variables followed by the environment variables. """ @@ -67,7 +67,7 @@ RETURN = r""" msg: description: - The msg indicates if the C(data) is valid as per the C(criteria). - - In case data is valid return success message I(all checks passed) + - In case data is valid return success message I(all checks passed). - In case data is invalid return error message I(Validation errors were found) along with more information on error is available. returned: always