doc fixes (#134)
Minor documentation fixes SUMMARY Minor documentation fixes and updated doc-string ISSUE TYPE Docs Pull Request Reviewed-by: Ashwini Mhatre <mashu97@gmail.com> Reviewed-by: None <None>pull/134/merge
Sagar Paul
GitHub
parent
ad9d3e1399
commit
9294a2df8f
31
README.md
31
README.md
|
|
@ -10,6 +10,8 @@ The Ansible ``ansible.utils`` collection includes a variety of plugins that aid
|
|||
|
||||
This collection has been tested against following Ansible versions: **>=2.9.10**.
|
||||
|
||||
For collections that support Ansible 2.9, please ensure you update your `network_os` to use the
|
||||
fully qualified collection name (for example, `cisco.ios.ios`).
|
||||
Plugins and modules within a collection may be tested with only specific Ansible versions.
|
||||
A collection may contain metadata that identifies these versions.
|
||||
PEP440 is the schema used to describe the versions of Ansible.
|
||||
|
|
@ -26,28 +28,25 @@ 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.hwaddr](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.hwaddr_filter.rst)|HWaddr / MAC address filters
|
||||
[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.keep_keys](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.keep_keys_filter.rst)|Keep specific keys from a data recursively.
|
||||
[ansible.utils.nthhost](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.nthhost_filter.rst)|This filter returns the nth host within a network described by value.
|
||||
[ansible.utils.ipv4](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.ipv4_filter.rst)|To filter only Ipv4 addresses Ipv4 filter is used.
|
||||
[ansible.utils.param_list_compare](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.param_list_compare_filter.rst)|Generate the final param list combining/comparing base and provided parameters.
|
||||
[ansible.utils.remove_keys](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.remove_keys_filter.rst)|Remove specific keys from a data recursively.
|
||||
[ansible.utils.replace_keys](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.replace_keys_filter.rst)|Replaces specific keys with their after value from a data recursively.
|
||||
[ansible.utils.macaddr](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.macaddr_filter.rst)|macaddr / MAC address filters
|
||||
[ansible.utils.slaac](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.slaac_filter.rst)|This filter returns the SLAAC address within a network for a given HW/MAC address.
|
||||
[ansible.utils.ipaddr](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.ipaddr_filter.rst)|This filter is designed to return the input value if a query is True, else False.
|
||||
[ansible.utils.ipwrap](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.ipwrap_filter.rst)|This filter is designed to Wrap IPv6 addresses in [ ] brackets.
|
||||
[ansible.utils.network_in_usable](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.network_in_usable_filter.rst)|The network_in_usable filter returns whether an address passed as an argument is usable in a network.
|
||||
[ansible.utils.network_in_network](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.network_in_network_filter.rst)|This filter returns whether an address or a network passed as argument is in a network.
|
||||
[ansible.utils.next_nth_usable](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.next_nth_usable_filter.rst)|This filter returns the next nth usable ip within a network described by value.
|
||||
[ansible.utils.ipsubnet](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.ipsubnet_filter.rst)|This filter can be used to manipulate network subnets in several ways.
|
||||
[ansible.utils.ipv6](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.ipv6_filter.rst)|To filter only Ipv6 addresses Ipv6 filter is used.
|
||||
[ansible.utils.ip4_hex](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.ip4_hex_filter.rst)|This filter is designed to convert IPv4 address to Hexadecimal notation with optional delimiter.
|
||||
[ansible.utils.ipaddr](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.ipaddr_filter.rst)|This filter is designed to return the input value if a query is True, else False.
|
||||
[ansible.utils.ipmath](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.ipmath_filter.rst)|This filter is designed to do simple IP math/arithmetic.
|
||||
[ansible.utils.nthhost](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.nthhost_filter.rst)|This filter returns the nth host within a network described by value.
|
||||
[ansible.utils.ipsubnet](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.ipsubnet_filter.rst)|This filter can be used to manipulate network subnets in several ways.
|
||||
[ansible.utils.ipv4](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.ipv4_filter.rst)|To filter only Ipv4 addresses Ipv4 filter is used.
|
||||
[ansible.utils.ipv6](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.ipv6_filter.rst)|To filter only Ipv6 addresses Ipv6 filter is used.
|
||||
[ansible.utils.ipwrap](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.ipwrap_filter.rst)|This filter is designed to Wrap IPv6 addresses in [ ] brackets.
|
||||
[ansible.utils.keep_keys](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.keep_keys_filter.rst)|Keep specific keys from a data recursively.
|
||||
[ansible.utils.macaddr](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.macaddr_filter.rst)|macaddr / MAC address filters
|
||||
[ansible.utils.network_in_network](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.network_in_network_filter.rst)|This filter returns whether an address or a network passed as argument is in a network.
|
||||
[ansible.utils.network_in_usable](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.network_in_usable_filter.rst)|The network_in_usable filter returns whether an address passed as an argument is usable in a network.
|
||||
[ansible.utils.next_nth_usable](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.next_nth_usable_filter.rst)|This filter returns the next nth usable ip within a network described by value.
|
||||
[ansible.utils.nthhost](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.nthhost_filter.rst)|This filter returns the nth host within a network described by value.
|
||||
[ansible.utils.param_list_compare](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.param_list_compare_filter.rst)|Generate the final param list combining/comparing base and provided parameters.
|
||||
[ansible.utils.previous_nth_usable](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.previous_nth_usable_filter.rst)|This filter returns the previous nth usable ip within a network described by value.
|
||||
[ansible.utils.reduce_on_network](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.reduce_on_network_filter.rst)|This filter reduces a list of addresses to only the addresses that match a given network.
|
||||
[ansible.utils.remove_keys](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.remove_keys_filter.rst)|Remove specific keys from a data recursively.
|
||||
[ansible.utils.replace_keys](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.replace_keys_filter.rst)|Replaces specific keys with their after value from a data recursively.
|
||||
[ansible.utils.slaac](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.slaac_filter.rst)|This filter returns the SLAAC address within a network for a given HW/MAC address.
|
||||
[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.to_xml](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.to_xml_filter.rst)|Convert given JSON string to XML
|
||||
[ansible.utils.usable_range](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.usable_range_filter.rst)|Expand the usable IP addresses
|
||||
|
|
|
|||
|
|
@ -0,0 +1,3 @@
|
|||
---
|
||||
doc_changes:
|
||||
- "Enhancement in documentation and docstring."
|
||||
|
|
@ -93,7 +93,7 @@ Examples
|
|||
- debug:
|
||||
msg: "{{ value|ansible.utils.cidr_merge }}"
|
||||
|
||||
# TASK [cidr_merge with merge action] ******************************************************************************************************************************
|
||||
# TASK [cidr_merge with merge action] **********************************************************************************
|
||||
# ok: [localhost] => {
|
||||
# "ansible_facts": {
|
||||
# "value": [
|
||||
|
|
@ -104,7 +104,7 @@ Examples
|
|||
# },
|
||||
# "changed": false
|
||||
# }
|
||||
# TASK [debug] *****************************************************************************************************************************************************
|
||||
# TASK [debug] *********************************************************************************************************
|
||||
# ok: [loalhost] => {
|
||||
# "msg": [
|
||||
# "192.168.0.0/16"
|
||||
|
|
|
|||
|
|
@ -101,7 +101,7 @@ Examples
|
|||
|
||||
.. code-block:: yaml
|
||||
|
||||
# Update an exisitng fact, dot or bracket notation
|
||||
# Update an existing fact, dot or bracket notation
|
||||
- name: Set a fact
|
||||
ansible.builtin.set_fact:
|
||||
a:
|
||||
|
|
|
|||
|
|
@ -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 <code>config_data|ansible.utils.validate(config_criteria, engine='ansible.utils.jsonschema'</code>), in this case the value <code>ansible.utils.jsonschema</code> represents the engine to be use for data validation. If the value is not provided the default value that is <code>ansible.uitls.jsonschema</code> will be used.</div>
|
||||
<div>This option can be passed in lookup plugin as a key, value pair. For example <code>config_data|ansible.utils.validate(config_criteria, engine='ansible.utils.jsonschema'</code>), in this case the value <code>ansible.utils.jsonschema</code> represents the engine to be use for data validation. If the value is not provided the default value that is <code>ansible.utils.jsonschema</code> will be used.</div>
|
||||
<div>The value should be in fully qualified collection name format that is <code><org-name>.<collection-name>.<validator-plugin-name></code>.</div>
|
||||
</td>
|
||||
</tr>
|
||||
|
|
@ -121,7 +121,7 @@ Examples
|
|||
|
||||
- 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') }}"
|
||||
data_validity: "{{ data|ansible.utils.validate(criteria, engine='ansible.utils.jsonschema', draft='draft7') }}"
|
||||
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -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 <code>lookup(config_data, config_criteria, engine='ansible.utils.jsonschema'</code>), in this case the value <code>ansible.utils.jsonschema</code> represents the engine to be use for data validation. If the value is not provided the default value that is <code>ansible.uitls.jsonschema</code> will be used.</div>
|
||||
<div>This option can be passed in lookup plugin as a key, value pair. For example <code>lookup(config_data, config_criteria, engine='ansible.utils.jsonschema'</code>), in this case the value <code>ansible.utils.jsonschema</code> represents the engine to be use for data validation. If the value is not provided the default value that is <code>ansible.utils.jsonschema</code> will be used.</div>
|
||||
<div>The value should be in fully qualified collection name format that is <code><org-name>.<collection-name>.<validate-plugin-name></code>.</div>
|
||||
</td>
|
||||
</tr>
|
||||
|
|
|
|||
|
|
@ -44,8 +44,7 @@ ARGSPEC_CONDITIONALS = {
|
|||
|
||||
|
||||
class ActionModule(ActionBase):
|
||||
""" action module
|
||||
"""
|
||||
"""action module"""
|
||||
|
||||
PARSER_CLS_NAME = "CliParser"
|
||||
|
||||
|
|
@ -140,7 +139,7 @@ class ActionModule(ActionBase):
|
|||
)
|
||||
return parser
|
||||
except Exception as exc:
|
||||
# TODO: The condition is added to support old sub-plugin strucutre.
|
||||
# TODO: The condition is added to support old sub-plugin structure.
|
||||
# Remove the if condition after ansible.netcommon.cli_parse module is removed
|
||||
# from ansible.netcommon collection
|
||||
if cref["cname"] == "netcommon" and cref["plugin"] in [
|
||||
|
|
@ -175,8 +174,7 @@ class ActionModule(ActionBase):
|
|||
return None
|
||||
|
||||
def _set_parser_command(self):
|
||||
""" Set the /parser/command in the task args based on /command if needed
|
||||
"""
|
||||
"""Set the /parser/command in the task args based on /command if needed"""
|
||||
if self._task.args.get("command"):
|
||||
if not self._task.args.get("parser").get("command"):
|
||||
self._task.args.get("parser")["command"] = self._task.args.get(
|
||||
|
|
@ -184,8 +182,7 @@ class ActionModule(ActionBase):
|
|||
)
|
||||
|
||||
def _set_text(self):
|
||||
""" Set the /text in the task_args based on the command run
|
||||
"""
|
||||
"""Set the /text in the task_args based on the command run"""
|
||||
if self._result.get("stdout"):
|
||||
self._task.args["text"] = self._result["stdout"]
|
||||
|
||||
|
|
|
|||
|
|
@ -35,7 +35,7 @@ DOCUMENTATION = """
|
|||
- This option can be passed in lookup plugin as a key, value pair.
|
||||
For example C(config_data|ansible.utils.validate(config_criteria, engine='ansible.utils.jsonschema')), in
|
||||
this case the value C(ansible.utils.jsonschema) represents the engine to be use for data validation.
|
||||
If the value is not provided the default value that is C(ansible.uitls.jsonschema) will be used.
|
||||
If the value is not provided the default value that is C(ansible.utils.jsonschema) will be used.
|
||||
- The value should be in fully qualified collection name format that is
|
||||
C(<org-name>.<collection-name>.<validator-plugin-name>).
|
||||
default: ansible.utils.jsonschema
|
||||
|
|
@ -58,7 +58,7 @@ EXAMPLES = r"""
|
|||
|
||||
- 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') }}"
|
||||
data_validity: "{{ data|ansible.utils.validate(criteria, engine='ansible.utils.jsonschema', draft='draft7') }}"
|
||||
"""
|
||||
|
||||
RETURN = """
|
||||
|
|
|
|||
|
|
@ -42,7 +42,7 @@ DOCUMENTATION = """
|
|||
- This option can be passed in lookup plugin as a key, value pair.
|
||||
For example C(lookup(config_data, config_criteria, engine='ansible.utils.jsonschema')), in
|
||||
this case the value C(ansible.utils.jsonschema) represents the engine to be use for data validation.
|
||||
If the value is not provided the default value that is C(ansible.uitls.jsonschema) will be used.
|
||||
If the value is not provided the default value that is C(ansible.utils.jsonschema) will be used.
|
||||
- The value should be in fully qualified collection name format that is
|
||||
C(<org-name>.<collection-name>.<validate-plugin-name>).
|
||||
default: ansible.utils.jsonschema
|
||||
|
|
|
|||
|
|
@ -141,7 +141,7 @@ class AnsibleArgSpecValidator:
|
|||
other_args=None,
|
||||
):
|
||||
"""Validate some data against a schema
|
||||
:param data: The data to valdiate
|
||||
:param data: The data to validate
|
||||
:type data: dict
|
||||
:param schema: A schema in ansible argspec format
|
||||
:type schema: dict
|
||||
|
|
|
|||
|
|
@ -66,7 +66,7 @@ def _run_test(entry, test, right, tests):
|
|||
:type test: a lambda from the qual_map
|
||||
:param entry: The x for the lambda
|
||||
:type entry: str int or bool
|
||||
:param right: The y for the lamba
|
||||
:param right: The y for the lambda
|
||||
:type right: str int bool or list
|
||||
:return: If the test passed
|
||||
:rtype: book
|
||||
|
|
@ -134,7 +134,7 @@ def index_of(
|
|||
:param data: The data passed in (data|index_of(...))
|
||||
:type data: unknown
|
||||
:param test: the test to use
|
||||
:type test: jinj2 test
|
||||
:type test: jinja2 test
|
||||
:param value: The value to use for the test
|
||||
:type value: unknown
|
||||
:param key: The key to use when a list of dicts is passed
|
||||
|
|
|
|||
|
|
@ -49,7 +49,7 @@ author:
|
|||
|
||||
EXAMPLES = r"""
|
||||
|
||||
# Update an exisitng fact, dot or bracket notation
|
||||
# Update an existing fact, dot or bracket notation
|
||||
- name: Set a fact
|
||||
ansible.builtin.set_fact:
|
||||
a:
|
||||
|
|
|
|||
|
|
@ -53,7 +53,7 @@ from ansible_collections.ansible.utils.plugins.module_utils.common.utils import
|
|||
to_list,
|
||||
)
|
||||
|
||||
# PY2 compatiblilty for JSONDecodeError
|
||||
# PY2 compatibility for JSONDecodeError
|
||||
try:
|
||||
from json.decoder import JSONDecodeError
|
||||
except ImportError:
|
||||
|
|
@ -86,7 +86,7 @@ class Validate(ValidateBase):
|
|||
def _check_reqs():
|
||||
"""Check the prerequisites are installed for jsonschema
|
||||
|
||||
:return None: In case all prerequisites are satisfised
|
||||
:return None: In case all prerequisites are satisfied
|
||||
"""
|
||||
if not HAS_JSONSCHEMA:
|
||||
raise AnsibleError(missing_required_lib("jsonschema"))
|
||||
|
|
|
|||
Loading…
Reference in New Issue