From 9294a2df8f21e0e76a163dcfe8b0dee14ef6e611 Mon Sep 17 00:00:00 2001 From: Sagar Paul Date: Mon, 31 Jan 2022 16:00:34 +0530 Subject: [PATCH] doc fixes (#134) Minor documentation fixes SUMMARY Minor documentation fixes and updated doc-string ISSUE TYPE Docs Pull Request Reviewed-by: Ashwini Mhatre Reviewed-by: None --- README.md | 31 +++++++++---------- .../fragments/docfix_minor_corrections.yaml | 3 ++ docs/ansible.utils.cidr_merge_filter.rst | 8 ++--- docs/ansible.utils.keep_keys_filter.rst | 4 +-- docs/ansible.utils.update_fact_module.rst | 2 +- docs/ansible.utils.validate_filter.rst | 4 +-- docs/ansible.utils.validate_lookup.rst | 2 +- plugins/action/cli_parse.py | 31 +++++++++---------- plugins/filter/validate.py | 6 ++-- plugins/lookup/validate.py | 2 +- .../module_utils/common/argspec_validate.py | 2 +- plugins/module_utils/common/index_of.py | 4 +-- plugins/modules/update_fact.py | 2 +- plugins/sub_plugins/validate/jsonschema.py | 4 +-- 14 files changed, 52 insertions(+), 53 deletions(-) create mode 100644 changelogs/fragments/docfix_minor_corrections.yaml diff --git a/README.md b/README.md index f76b280..57d5e8f 100644 --- a/README.md +++ b/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 diff --git a/changelogs/fragments/docfix_minor_corrections.yaml b/changelogs/fragments/docfix_minor_corrections.yaml new file mode 100644 index 0000000..2282e6b --- /dev/null +++ b/changelogs/fragments/docfix_minor_corrections.yaml @@ -0,0 +1,3 @@ +--- +doc_changes: + - "Enhancement in documentation and docstring." diff --git a/docs/ansible.utils.cidr_merge_filter.rst b/docs/ansible.utils.cidr_merge_filter.rst index ebb001d..c13daa7 100644 --- a/docs/ansible.utils.cidr_merge_filter.rst +++ b/docs/ansible.utils.cidr_merge_filter.rst @@ -85,7 +85,7 @@ Examples #### examples - name: cidr_merge with merge action - ansible.builtin.set_fact: + ansible.builtin.set_fact: value: - 192.168.0.0/17 - 192.168.128.0/17 @@ -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" @@ -112,7 +112,7 @@ Examples # } - name: Cidr_merge with span. - ansible.builtin.set_fact: + ansible.builtin.set_fact: value: - 192.168.1.1 - 192.168.1.2 diff --git a/docs/ansible.utils.keep_keys_filter.rst b/docs/ansible.utils.keep_keys_filter.rst index 78071cf..c281088 100644 --- a/docs/ansible.utils.keep_keys_filter.rst +++ b/docs/ansible.utils.keep_keys_filter.rst @@ -277,8 +277,8 @@ Examples ansible.builtin.set_fact: data: "{{ interfaces }}" - - debug: - msg: "{{ data|ansible.utils.keep_keys(target=['desc', 'name'], matching_parameter= 'starts_with') }}" + - debug: + msg: "{{ data|ansible.utils.keep_keys(target=['desc', 'name'], matching_parameter= 'starts_with') }}" ##Output # TASK [keep selective keys from python dict/list of dict] ************************** diff --git a/docs/ansible.utils.update_fact_module.rst b/docs/ansible.utils.update_fact_module.rst index 675cbc4..27676ab 100644 --- a/docs/ansible.utils.update_fact_module.rst +++ b/docs/ansible.utils.update_fact_module.rst @@ -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: diff --git a/docs/ansible.utils.validate_filter.rst b/docs/ansible.utils.validate_filter.rst index 91b5b16..7e1a840 100644 --- a/docs/ansible.utils.validate_filter.rst +++ b/docs/ansible.utils.validate_filter.rst @@ -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 validation. 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 validation. If the value is not provided the default value that is ansible.utils.jsonschema will be used.
The value should be in fully qualified collection name format that is <org-name>.<collection-name>.<validator-plugin-name>.
@@ -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') }}" diff --git a/docs/ansible.utils.validate_lookup.rst b/docs/ansible.utils.validate_lookup.rst index 84a4e22..8917876 100644 --- a/docs/ansible.utils.validate_lookup.rst +++ b/docs/ansible.utils.validate_lookup.rst @@ -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 validation. 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 validation. If the value is not provided the default value that is ansible.utils.jsonschema will be used.
The value should be in fully qualified collection name format that is <org-name>.<collection-name>.<validate-plugin-name>.
diff --git a/plugins/action/cli_parse.py b/plugins/action/cli_parse.py index 2b1c6a8..c3fba9e 100644 --- a/plugins/action/cli_parse.py +++ b/plugins/action/cli_parse.py @@ -44,8 +44,7 @@ ARGSPEC_CONDITIONALS = { class ActionModule(ActionBase): - """ action module - """ + """action module""" PARSER_CLS_NAME = "CliParser" @@ -57,7 +56,7 @@ class ActionModule(ActionBase): self._task_vars = None def _debug(self, msg): - """ Output text using ansible's display + """Output text using ansible's display :param msg: The message :type msg: str @@ -68,7 +67,7 @@ class ActionModule(ActionBase): self._display.vvvv(msg) def _fail_json(self, msg): - """ Replace the AnsibleModule fai_json here + """Replace the AnsibleModule fai_json here :param msg: The message for the failure :type msg: str @@ -77,7 +76,7 @@ class ActionModule(ActionBase): raise AnsibleActionFail(msg) def _extended_check_argspec(self): - """ Check additional requirements for the argspec + """Check additional requirements for the argspec that cannot be covered using stnd techniques """ errors = [] @@ -101,7 +100,7 @@ class ActionModule(ActionBase): self._result["msg"] = " ".join(errors) def _load_parser(self, task_vars): - """ Load a parser from the fs + """Load a parser from the fs :param task_vars: The vars provided when the task was run :type task_vars: dict @@ -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,13 +182,12 @@ 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"] def _os_from_task_vars(self): - """ Extract an os str from the task's vars + """Extract an os str from the task's vars :return: A short OS name :rtype: str @@ -216,7 +213,7 @@ class ActionModule(ActionBase): return oper_sys.lower() def _update_template_path(self, template_extension): - """ Update the template_path in the task args + """Update the template_path in the task args If not provided, generate template name using os and command :param template_extension: The parser specific template extension @@ -242,7 +239,7 @@ class ActionModule(ActionBase): self._task.args["parser"]["template_path"] = source def _get_template_contents(self): - """ Retrieve the contents of the parser template + """Retrieve the contents of the parser template :return: The parser's contents :rtype: str @@ -269,7 +266,7 @@ class ActionModule(ActionBase): return template_contents def _prune_result(self): - """ In the case of an error, remove stdout and stdout_lines + """In the case of an error, remove stdout and stdout_lines this allows for easier visibility of the error message. In the case of an actual command error, it will be thrown in the module @@ -278,7 +275,7 @@ class ActionModule(ActionBase): self._result.pop("stdout_lines", None) def _run_command(self): - """ Run a command on the host + """Run a command on the host If socket_path exists, assume it's a network device else, run a low level command """ @@ -303,7 +300,7 @@ class ActionModule(ActionBase): self._result["stdout_lines"] = result["stdout_lines"] def run(self, tmp=None, task_vars=None): - """ The std execution entry pt for an action plugin + """The std execution entry pt for an action plugin :param tmp: no longer used :type tmp: none diff --git a/plugins/filter/validate.py b/plugins/filter/validate.py index 681ae8f..c8b1a9c 100644 --- a/plugins/filter/validate.py +++ b/plugins/filter/validate.py @@ -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(..). 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 = """ @@ -138,7 +138,7 @@ def validate(*args, **kwargs): class FilterModule(object): - """ index_of """ + """index_of""" def filters(self): """a mapping of filter names to functions""" diff --git a/plugins/lookup/validate.py b/plugins/lookup/validate.py index 09f615b..2fe1fa3 100644 --- a/plugins/lookup/validate.py +++ b/plugins/lookup/validate.py @@ -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(..). default: ansible.utils.jsonschema diff --git a/plugins/module_utils/common/argspec_validate.py b/plugins/module_utils/common/argspec_validate.py index 2c2afc3..599fafa 100644 --- a/plugins/module_utils/common/argspec_validate.py +++ b/plugins/module_utils/common/argspec_validate.py @@ -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 diff --git a/plugins/module_utils/common/index_of.py b/plugins/module_utils/common/index_of.py index 331e2e1..01b2393 100644 --- a/plugins/module_utils/common/index_of.py +++ b/plugins/module_utils/common/index_of.py @@ -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 diff --git a/plugins/modules/update_fact.py b/plugins/modules/update_fact.py index 649ea66..1659376 100644 --- a/plugins/modules/update_fact.py +++ b/plugins/modules/update_fact.py @@ -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: diff --git a/plugins/sub_plugins/validate/jsonschema.py b/plugins/sub_plugins/validate/jsonschema.py index e749500..53e2355 100644 --- a/plugins/sub_plugins/validate/jsonschema.py +++ b/plugins/sub_plugins/validate/jsonschema.py @@ -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"))