a-c-m
/
ansible.utils
mirror of https://github.com/ansible-collections/ansible.utils.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

[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
pull/30/head
Sandra McCann 2020-12-03 01:03:43 -05:00 committed by GitHub
parent a22cbd97b2
commit c9434fa95f
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
25 changed files with 247 additions and 240 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

23
README.md
View File

@ -3,7 +3,7 @@
# 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.
<!--start requires_ansible-->
## 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
<!--end collection content-->
## 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

3
changelogs/fragments/docs_copyedit.yaml Normal file
View File

@ -0,0 +1,3 @@
---
trivial:
- Edited the documentation

20
docs/ansible.utils.fact_diff_module.rst
View File

@ -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
<td>
</td>
<td>
<div>The second fact to be used in the comparison</div>
<div>The second fact to be used in the comparison.</div>
</td>
</tr>
<tr>
@ -62,7 +62,7 @@ Parameters
<td>
</td>
<td>
<div>The first fact to be used in the comparison</div>
<div>The first fact to be used in the comparison.</div>
</td>
</tr>
<tr>
@ -95,7 +95,7 @@ Parameters
<b>Default:</b><br/><div style="color: blue">"ansible.utils.native"</div>
</td>
<td>
<div>The diff plugin to use, in collection format</div>
<div>The diff plugin to use, in fully qualified collection name format.</div>
</td>
</tr>
<tr>
@ -112,7 +112,7 @@ Parameters
<b>Default:</b><br/><div style="color: blue">{}</div>
</td>
<td>
<div>Parameters passed to the diff plugin</div>
<div>Parameters passed to the diff plugin.</div>
</td>
</tr>
<tr>
@ -129,9 +129,9 @@ Parameters
<td>
</td>
<td>
<div>Skip lines matching these regular expressions</div>
<div>Matches will be removed prior to the diff</div>
<div>If the provided <em>before</em> and <em>after</em> are a string, they will be split</div>
<div>Skip lines matching these regular expressions.</div>
<div>Matches will be removed prior to the diff.</div>
<div>If the provided <em>before</em> and <em>after</em> are a string, they will be split.</div>
<div>Each entry in each list will be cast to a string for the comparison</div>
</td>
</tr>
@ -302,7 +302,7 @@ Common return values are documented `here <https://docs.ansible.com/ansible/late
</td>
<td>always</td>
<td>
<div>The <code>diff_text</code> split into lines</div>
<div>The <code>diff_text</code> split into lines.</div>
<br/>
</td>
</tr>
@ -317,7 +317,7 @@ Common return values are documented `here <https://docs.ansible.com/ansible/late
</td>
<td>always</td>
<td>
<div>The diff in text format</div>
<div>The diff in text format.</div>
<br/>
</td>
</tr>

18
docs/ansible.utils.get_path_filter.rst
View File

@ -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
</td>
<td>
<div>The <code>path</code> in the <code>var</code> to retrieve the value of.</div>
<div>The <code>path</code> needs to a be a valid jinja path</div>
<div>The <code>path</code> needs to be a valid jinja path.</div>
</td>
</tr>
<tr>
@ -70,8 +70,8 @@ Parameters
<td>
</td>
<td>
<div>The variable from which the value should be extraced</div>
<div>This option represents the value that is passed to filter plugin in pipe format.</div>
<div>The variable from which the value should be extracted.</div>
<div>This option represents the value that is passed to the filter plugin in pipe format.</div>
<div>For example <em>config_data|ansible.utils.get_path(</em>), in this case <em>config_data</em> represents this option.</div>
</td>
</tr>
@ -93,7 +93,7 @@ Parameters
<td>
</td>
<td>
<div>If set to <code>True</code>, the return value will always be a list</div>
<div>If set to <code>True</code>, the return value will always be a list.</div>
</td>
</tr>
</table>
@ -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]) =>

18
docs/ansible.utils.get_path_lookup.rst
View File

@ -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
<td>
</td>
<td>
<div>The <code>path</code> in the <code>var</code> to retrieve the value of. The <code>path</code> needs to a be a valid jinja path</div>
<div>The <code>path</code> in the <code>var</code> to retrieve the value of. The <code>path</code> needs to a be a valid jinja path.</div>
</td>
</tr>
<tr>
@ -69,7 +69,7 @@ Parameters
<td>
</td>
<td>
<div>The variable from which the value should be extraced</div>
<div>The variable from which the value should be extracted.</div>
</td>
</tr>
<tr>
@ -90,7 +90,7 @@ Parameters
<td>
</td>
<td>
<div>If set to <code>True</code>, the return value will always be a list This can also be accomplished using <code>query</code> or <code>q</code> instead of <code>lookup</code> <a href='https://docs.ansible.com/ansible/latest/plugins/lookup.html'>https://docs.ansible.com/ansible/latest/plugins/lookup.html</a></div>
<div>If set to <code>True</code>, the return value will always be a list. This can also be accomplished using <code>query</code> or <code>q</code> instead of <code>lookup</code>. <a href='https://docs.ansible.com/ansible/latest/plugins/lookup.html'>https://docs.ansible.com/ansible/latest/plugins/lookup.html</a>.</div>
</td>
</tr>
</table>
@ -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 <https://docs.ansible.com/ansible/late
</td>
<td></td>
<td>
<div>One or more zero-based indicies of the matching list items</div>
<div>See <code>wantlist</code> if a list is always required</div>
<div>One or more zero-based indices of the matching list items.</div>
<div>See <code>wantlist</code> if a list is always required.</div>
<br/>
</td>
</tr>

28
docs/ansible.utils.index_of_filter.rst
View File

@ -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
<td>
</td>
<td>
<div>A list of items to enumerate and test against</div>
<div>This option represents the value that is passed to filter plugin in pipe format.</div>
<div>A list of items to enumerate and test against.</div>
<div>This option represents the value that is passed to the filter plugin in pipe format.</div>
<div>For example <em>config_data|ansible.utils.index_of(&#x27;x&#x27;</em>), in this case <em>config_data</em> represents this option.</div>
</td>
</tr>
@ -75,7 +75,7 @@ Parameters
<td>
</td>
<td>
<div>When provided a list of dictionaries, fail if the key is missing from one or more of the dictionaries</div>
<div>When provided a list of dictionaries, fail if the key is missing from one or more of the dictionaries.</div>
</td>
</tr>
<tr>
@ -92,9 +92,9 @@ Parameters
<td>
</td>
<td>
<div>When the data provided is a list of dictionaries, run the test againt this dictionary key</div>
<div>When using a <code>key</code>, the <code>data</code> must only contain dictionaries</div>
<div>See <code>fail_on_missing</code> below to determine the behaviour when the <code>key</code> is missing from a dictionary in the <code>data</code></div>
<div>When the data provided is a list of dictionaries, run the test against this dictionary key.</div>
<div>When using a <code>key</code>, the <code>data</code> must only contain dictionaries.</div>
<div>See <code>fail_on_missing</code> below to determine the behavior when the <code>key</code> is missing from a dictionary in the <code>data</code>.</div>
</td>
</tr>
<tr>
@ -131,7 +131,7 @@ Parameters
<td>
</td>
<td>
<div>The value used to test each list item against</div>
<div>The value used to test each list item against.</div>
<div>{&#x27;Not required for simple tests (eg&#x27;: &#x27;<code>true</code>, <code>false</code>, <code>even</code>, <code>odd</code>)&#x27;}</div>
<div>May be a <code>string</code>, <code>boolean</code>, <code>number</code>, <code>regular expesion</code> <code>dict</code> etc, depending on the <code>test</code> used</div>
</td>
@ -154,8 +154,8 @@ Parameters
<td>
</td>
<td>
<div>When only a single entry in the <code>data</code> is matched, that entries index is returned as an integer</div>
<div>If set to <code>True</code>, the return value will always be a list, even if only a single entry is matched</div>
<div>When only a single entry in the <code>data</code> is matched, the index of that entry is returned as an integer.</div>
<div>If set to <code>True</code>, the return value will always be a list, even if only a single entry is matched.</div>
</td>
</tr>
</table>

28
docs/ansible.utils.index_of_lookup.rst
View File

@ -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
<td>
</td>
<td>
<div>A list of items to enumerate and test against</div>
<div>A list of items to enumerate and test against.</div>
</td>
</tr>
<tr>
@ -73,7 +73,7 @@ Parameters
<td>
</td>
<td>
<div>When provided a list of dictionaries, fail if the key is missing from one or more of the dictionaries</div>
<div>When provided a list of dictionaries, fail if the key is missing from one or more of the dictionaries.</div>
</td>
</tr>
<tr>
@ -90,7 +90,7 @@ Parameters
<td>
</td>
<td>
<div>When the data provided is a list of dictionaries, run the test againt this dictionary key When using a <code>key</code>, the <code>data</code> must only contain dictionaries See <code>fail_on_missing</code> below to determine the behaviour when the <code>key</code> is missing from a dictionary in the <code>data</code></div>
<div>When the data provided is a list of dictionaries, run the test against this dictionary key. When using a <code>key</code>, the <code>data</code> must only contain dictionaries. See <code>fail_on_missing</code> below to determine the behaviour when the <code>key</code> is missing from a dictionary in the <code>data</code>.</div>
</td>
</tr>
<tr>
@ -108,7 +108,7 @@ Parameters
<td>
</td>
<td>
<div>The name of the test to run against the list, a valid jinja2 test or ansible test plugin. Jinja2 includes the following tests <a href='http://jinja.palletsprojects.com/templates/#builtin-tests'>http://jinja.palletsprojects.com/templates/#builtin-tests</a>. An overview of tests included in ansible <a href='https://docs.ansible.com/ansible/latest/user_guide/playbooks_tests.html'>https://docs.ansible.com/ansible/latest/user_guide/playbooks_tests.html</a></div>
<div>The name of the test to run against the list, a valid jinja2 test or ansible test plugin. Jinja2 includes the following tests <a href='http://jinja.palletsprojects.com/templates/#builtin-tests'>http://jinja.palletsprojects.com/templates/#builtin-tests</a>. An overview of tests included in ansible <a href='https://docs.ansible.com/ansible/latest/user_guide/playbooks_tests.html'>https://docs.ansible.com/ansible/latest/user_guide/playbooks_tests.html</a>.</div>
</td>
</tr>
<tr>
@ -125,7 +125,7 @@ Parameters
<td>
</td>
<td>
<div>The value used to test each list item against Not required for simple tests (eg: <code>true</code>, <code>false</code>, <code>even</code>, <code>odd</code>) May be a <code>string</code>, <code>boolean</code>, <code>number</code>, <code>regular expesion</code> <code>dict</code> etc, depending on the <code>test</code> used</div>
<div>The value used to test each list item against. Not required for simple tests (eg: <code>true</code>, <code>false</code>, <code>even</code>, <code>odd</code>) May be a <code>string</code>, <code>boolean</code>, <code>number</code>, <code>regular expesion</code> <code>dict</code> etc, depending on the <code>test</code> used.</div>
</td>
</tr>
<tr>
@ -146,7 +146,7 @@ Parameters
<td>
</td>
<td>
<div>When only a single entry in the <code>data</code> is matched, that entries index is returned as an integer If set to <code>True</code>, the return value will always be a list, even if only a single entry is matched This can also be accomplised using <code>query</code> or <code>q</code> instead of <code>lookup</code> <a href='https://docs.ansible.com/ansible/latest/plugins/lookup.html'>https://docs.ansible.com/ansible/latest/plugins/lookup.html</a></div>
<div>When only a single entry in the <code>data</code> is matched, the index of that entry is returned as an integer. If set to <code>True</code>, the return value will always be a list, even if only a single entry is matched. This can also be accomplised using <code>query</code> or <code>q</code> instead of <code>lookup</code>. <a href='https://docs.ansible.com/ansible/latest/plugins/lookup.html'>https://docs.ansible.com/ansible/latest/plugins/lookup.html</a></div>
</td>
</tr>
</table>
@ -429,8 +429,8 @@ Common return values are documented `here <https://docs.ansible.com/ansible/late
</td>
<td></td>
<td>
<div>One or more zero-based indicies of the matching list items</div>
<div>See <code>wantlist</code> if a list is always required</div>
<div>One or more zero-based indicies of the matching list items.</div>
<div>See <code>wantlist</code> if a list is always required.</div>
<br/>
</td>
</tr>

5
docs/ansible.utils.jsonschema_validate.rst
View File

@ -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.

18
docs/ansible.utils.to_paths_filter.rst
View File

@ -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
</td>
<td>
<div>The value of <code>var</code> will be will be used.</div>
<div>This option represents the value that is passed to filter plugin in pipe format.</div>
<div>This option represents the value that is passed to the filter plugin in pipe format.</div>
<div>For example <em>config_data|ansible.utils.to_paths(</em>), in this case <em>config_data</em> represents this option.</div>
</td>
</tr>
@ -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

22
docs/ansible.utils.to_paths_lookup.rst
View File

@ -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 <https://docs.ansible.com/ansible/late
</td>
<td></td>
<td>
<div>A dictionary of key value pairs</div>
<div>The key is the path</div>
<div>The value is the value</div>
<div>A dictionary of key value pairs.</div>
<div>The key is the path.</div>
<div>The value is the value.</div>
<br/>
</td>
</tr>

16
docs/ansible.utils.update_fact_module.rst
View File

@ -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
<td>
</td>
<td>
<div>A list of dictionaries, each a desired update to make</div>
<div>A list of dictionaries, each a desired update to make.</div>
</td>
</tr>
<tr>
@ -66,9 +66,9 @@ Parameters
<td>
</td>
<td>
<div>The path in a currently set variable to update</div>
<div>The path can be in dot or bracket notation</div>
<div>It should be a valid jinja reference</div>
<div>The path in a currently set variable to update.</div>
<div>The path can be in dot or bracket notation.</div>
<div>It should be a valid jinja reference.</div>
</td>
</tr>
<tr>
@ -85,8 +85,8 @@ Parameters
<td>
</td>
<td>
<div>The value to be set at the path</div>
<div>Can be a simple or complex data structure</div>
<div>The value to be set at the path.</div>
<div>Can be a simple or complex data structure.</div>
</td>
</tr>
@ -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

18
docs/ansible.utils.validate_filter.rst
View File

@ -50,8 +50,8 @@ Parameters
</td>
<td>
<div>The criteria used for validation of value that represents <code>data</code> options.</div>
<div>This option represents the first argument passed in the filter plugin For example <em>config_data|ansible.utils.validate(config_criteria</em>), in this case the value of <em>config_criteria</em> represents this option.</div>
<div>For the type of <code>criteria</code> that represents this value refer documentation of individual validator plugins.</div>
<div>This option represents the first argument passed in the filter plugin. For example <em>config_data|ansible.utils.validate(config_criteria</em>), in this case the value of <em>config_criteria</em> represents this option.</div>
<div>For the type of <code>criteria</code> that represents this value refer to the documentation of individual validator plugins.</div>
</td>
</tr>
<tr>
@ -69,9 +69,9 @@ Parameters
<td>
</td>
<td>
<div>A data that will be validated against <code>criteria</code>.</div>
<div>This option represents the value that is passed to filter plugin in pipe format. For example <em>config_data|ansible.utils.validate(</em>), in this case <em>config_data</em> represents this option.</div>
<div>For the type of <code>data</code> that represents this value refer documentation of individual validator plugins.</div>
<div>Data that will be validated against <code>criteria</code>.</div>
<div>This option represents the value that is passed to the filter plugin in pipe format. For example <em>config_data|ansible.utils.validate(</em>), in this case <em>config_data</em> represents this option.</div>
<div>For the type of <code>data</code> that represents this value refer to the documentation of individual validator plugins.</div>
</td>
</tr>
<tr>
@ -90,7 +90,7 @@ Parameters
</td>
<td>
<div>The name of the validator plugin to use.</div>
<div>This option can be passed in lookup plugin as a key, value pair For example <em>config_data|ansible.utils.validate(config_criteria, engine=&#x27;ansible.utils.jsonschema&#x27;</em>), in this case the value <em>ansible.utils.jsonschema</em> represents the engine to be use for data valdiation. If the value is not provided the default value that is <em>ansible.uitls.jsonschema</em> will be used.</div>
<div>This option can be passed in lookup plugin as a key, value pair. For example <em>config_data|ansible.utils.validate(config_criteria, engine=&#x27;ansible.utils.jsonschema&#x27;</em>), in this case the value <em>ansible.utils.jsonschema</em> represents the engine to be use for data valdiation. If the value is not provided the default value that is <em>ansible.uitls.jsonschema</em> will be used.</div>
<div>The value should be in fully qualified collection name format that is <em>&lt;org-name&gt;.&lt;collection-name&gt;.&lt;validator-plugin-name&gt;</em>.</div>
</td>
</tr>
@ -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') }}"

18
docs/ansible.utils.validate_lookup.rst
View File

@ -51,7 +51,7 @@ Parameters
<td>
<div>The criteria used for validation of value that represents <code>data</code> options.</div>
<div>This option represents the second argument passed in the lookup plugin For example <em>lookup(config_data, config_criteria, engine=&#x27;ansible.utils.jsonschema&#x27;</em>), in this case the value of <em>config_criteria</em> represents this option.</div>
<div>For the type of <code>criteria</code> that represents this value refer documentation of individual validate plugins.</div>
<div>For the type of <code>criteria</code> that represents this value refer to the documentation of individual validate plugins.</div>
</td>
</tr>
<tr>
@ -69,9 +69,9 @@ Parameters
<td>
</td>
<td>
<div>A data that will be validated against <code>criteria</code>.</div>
<div>This option represents the value that is passed to lookup plugin as first argument. For example <em>lookup(config_data, config_criteria, engine=&#x27;ansible.utils.jsonschema&#x27;</em>), in this case <em>config_data</em> represents this option.</div>
<div>For the type of <code>data</code> that represents this value refer documentation of individual validate plugins.</div>
<div>Data that will be validated against <code>criteria</code>.</div>
<div>This option represents the value that is passed to the lookup plugin as the first argument. For example <em>lookup(config_data, config_criteria, engine=&#x27;ansible.utils.jsonschema&#x27;</em>), in this case <em>config_data</em> represents this option.</div>
<div>For the type of <code>data</code> that represents this value refer to the documentation of individual validate plugins.</div>
</td>
</tr>
<tr>
@ -90,7 +90,7 @@ Parameters
</td>
<td>
<div>The name of the validate plugin to use.</div>
<div>This option can be passed in lookup plugin as a key, value pair For example <em>lookup(config_data, config_criteria, engine=&#x27;ansible.utils.jsonschema&#x27;</em>), in this case the value <em>ansible.utils.jsonschema</em> represents the engine to be use for data valdiation. If the value is not provided the default value that is <em>ansible.uitls.jsonschema</em> will be used.</div>
<div>This option can be passed in lookup plugin as a key, value pair. For example <em>lookup(config_data, config_criteria, engine=&#x27;ansible.utils.jsonschema&#x27;</em>), in this case the value <em>ansible.utils.jsonschema</em> represents the engine to be use for data valdiation. If the value is not provided the default value that is <em>ansible.uitls.jsonschema</em> will be used.</div>
<div>The value should be in fully qualified collection name format that is <em>&lt;org-name&gt;.&lt;collection-name&gt;.&lt;validate-plugin-name&gt;</em>.</div>
</td>
</tr>
@ -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 <https://docs.ansible.com/ansible/late
</td>
<td></td>
<td>
<div>If data is valid returns empty list</div>
<div>If data is invalid returns list of errors in data</div>
<div>If data is valid returns empty list.</div>
<div>If data is invalid returns list of errors in data.</div>
<br/>
</td>
</tr>

14
docs/ansible.utils.validate_module.rst
View File

@ -46,7 +46,7 @@ Parameters
<td>
</td>
<td>
<div>The criteria used for validation of <code>data</code>. For the type of criteria refer documentation of individual validate plugins.</div>
<div>The criteria used for validation of <code>data</code>. For the type of criteria refer to the documentation of individual validate plugins.</div>
</td>
</tr>
<tr>
@ -62,7 +62,7 @@ Parameters
<td>
</td>
<td>
<div>A data that will be validated against <code>criteria</code>. For the type of data refer documentation of individual validate plugins</div>
<div>Data that will be validated against <code>criteria</code>. For the type of data refer to the documentation of individual validate plugins.</div>
</td>
</tr>
<tr>
@ -78,7 +78,7 @@ Parameters
<b>Default:</b><br/><div style="color: blue">"ansible.utils.jsonschema"</div>
</td>
<td>
<div>The name of the validate plugin to use. The engine value should follow the fully qualified collection name format that is &lt;org-name&gt;.&lt;collection-name&gt;.&lt;validate-plugin-name&gt;.</div>
<div>The name of the validate plugin to use. The engine value should follow the fully qualified collection name format, that is &lt;org-name&gt;.&lt;collection-name&gt;.&lt;validate-plugin-name&gt;.</div>
</td>
</tr>
</table>
@ -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 <https://docs.ansible.com/ansible/late
<td>always</td>
<td>
<div>The msg indicates if the <code>data</code> is valid as per the <code>criteria</code>.</div>
<div>In case data is valid return success message <em>all checks passed</em></div>
<div>In case data is valid return success message <em>all checks passed</em>.</div>
<div>In case data is invalid return error message <em>Validation errors were found</em> along with more information on error is available.</div>
<br/>
</td>

18
plugins/filter/get_path.py
View File

@ -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]) =>

28
plugins/filter/index_of.py
View File

@ -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:

18
plugins/filter/to_paths.py
View File

@ -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

18
plugins/filter/validate.py
View File

@ -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(<org-name>.<collection-name>.<validator-plugin-name>).
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') }}"
"""

22
plugins/lookup/get_path.py
View File

@ -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

38
plugins/lookup/index_of.py
View File

@ -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

22
plugins/lookup/to_paths.py
View File

@ -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

18
plugins/lookup/validate.py
View File

@ -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(<org-name>.<collection-name>.<validate-plugin-name>).
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

20
plugins/modules/fact_diff.py
View File

@ -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

16
plugins/modules/update_fact.py
View File

@ -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

16
plugins/modules/validate.py
View File

@ -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 fully qualified collection name format, that is
<org-name>.<collection-name>.<validate-plugin-name>.
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