diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml new file mode 100644 index 0000000..6d40332 --- /dev/null +++ b/.github/workflows/test.yml @@ -0,0 +1,26 @@ +name: Test collection +on: + push: + branches: [main] + pull_request: + branches: [main] + workflow_dispatch: + +jobs: + sanity: + uses: ansible-network/github_actions/.github/workflows/sanity.yml@main + unit-galaxy: + uses: ansible-network/github_actions/.github/workflows/unit_simple.yml@main + + all_green: + if: ${{ always() }} + needs: + - sanity + - unit-galaxy + runs-on: ubuntu-latest + steps: + - run: >- + python -c "assert set([ + '${{ needs.sanity.result }}', + '${{ needs.unit-galaxy.result }}' + ]) == {'success'}" diff --git a/changelogs/fragments/172.yaml b/changelogs/fragments/172.yaml new file mode 100644 index 0000000..323b394 --- /dev/null +++ b/changelogs/fragments/172.yaml @@ -0,0 +1,4 @@ +--- +trivial: + - Enable GH action for unit ans sanity tests + - Several minor doc string updates to get sanity to pass with devel/milestone diff --git a/plugins/lookup/get_path.py b/plugins/lookup/get_path.py index fb9349e..5b281ab 100644 --- a/plugins/lookup/get_path.py +++ b/plugins/lookup/get_path.py @@ -18,25 +18,26 @@ DOCUMENTATION = """ version_added: "1.0.0" short_description: Retrieve the value in a variable using a path description: - - Use a I(path) to retrieve a nested value from a I(var) - - B(get_path) is also available as a B(filter plugin) for convenience - - Using the parameters below- C(lookup('ansible.utils.get_path', var, path, wantlist)) + - Use a I(path) to retrieve a nested value from a I(var) + - B(get_path) is also available as a B(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 extracted. + description: + - The variable from which the value should be extracted. type: raw required: True path: - description: > - The I(path) in the I(var) to retrieve the value of. - The I(path) needs to a be a valid jinja path. + description: + - The I(path) in the I(var) to retrieve the value of. + - The I(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). + 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). type: bool notes: @@ -170,8 +171,10 @@ class LookupModule(LookupBase): keys = ["var", "path"] terms = dict(zip(keys, terms)) terms.update(kwargs) + + schema = [v for k, v in globals() if k.lower() == "documentation"] aav = AnsibleArgSpecValidator( - data=terms, schema=DOCUMENTATION, name="get_path" + data=terms, schema=schema[0], name="get_path" ) valid, errors, updated_data = aav.validate() if not valid: diff --git a/plugins/lookup/index_of.py b/plugins/lookup/index_of.py index f584a32..82835e1 100644 --- a/plugins/lookup/index_of.py +++ b/plugins/lookup/index_of.py @@ -17,45 +17,47 @@ DOCUMENTATION = """ author: Bradley Thornton (@cidrblock) version_added: "1.0.0" short_description: Find the indices of items in a list matching some criteria - description: - - 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. - - B(index_of) is also available as a B(filter plugin) for convenience. - - Using the parameters below- C(lookup('ansible.utils.index_of', data, test, value, key, fail_on_missing, wantlist)). + description: foo + - 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. + - B(index_of) is also available as a B(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 elements: raw 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). + 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). type: str required: True value: - description: > - 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 expression) C(dict) and so on, depending on the B(test) used. + description: + - The value used to test each list item against. + - Not required for simple tests (e.g. C(true), C(false), C(even), C(odd)) + - May be a C(string), C(boolean), C(number), C(regular expression) C(dict) and so on, depending on the B(test) used. type: raw key: - description: > - When the data provided is a list of dictionaries, run the test against this dictionary key. - When using a I(key), the I(data) must only contain dictionaries. - See I(fail_on_missing) below to determine the behaviour when the I(key) is missing from a dictionary in the I(data). + description: + - When the data provided is a list of dictionaries, run the test against this dictionary key. + - When using a I(key), the I(data) must only contain dictionaries. + - See I(fail_on_missing) below to determine the behaviour when the I(key) is missing from a dictionary in the I(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 I(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 accomplished using C(query) or C(q) instead of C(lookup). - U(https://docs.ansible.com/ansible/latest/plugins/lookup.html) + description: + - When only a single entry in the I(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 accomplished using C(query) or C(q) instead of C(lookup). + - U(https://docs.ansible.com/ansible/latest/plugins/lookup.html) type: bool notes: @@ -338,8 +340,10 @@ class LookupModule(LookupBase): ] terms = dict(zip(keys, terms)) terms.update(kwargs) + + schema = [v for k, v in globals() if k.lower() == "documentation"] aav = AnsibleArgSpecValidator( - data=terms, schema=DOCUMENTATION, name="index_of" + data=terms, schema=schema[0], name="index_of" ) valid, errors, updated_data = aav.validate() if not valid: diff --git a/plugins/lookup/to_paths.py b/plugins/lookup/to_paths.py index c8b72ab..94f15a4 100644 --- a/plugins/lookup/to_paths.py +++ b/plugins/lookup/to_paths.py @@ -18,25 +18,27 @@ DOCUMENTATION = """ 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. - - Brackets are used for list indices and keys that contain special characters. - - B(to_paths) is also available as a filter plugin. - - Using the parameters below- C(lookup('ansible.utils.to_paths', var, prepend, wantlist)) + - Flatten a complex object into a dictionary of paths and values. + - Paths are dot delimited whenever possible. + - Brackets are used for list indices and keys that contain special characters. + - B(to_paths) is also available as a filter plugin. + - Using the parameters below- C(lookup('ansible.utils.to_paths', var, prepend, wantlist)) options: var: - description: The value of I(var) will be used. + description: + - The value of I(var) will be used. type: raw required: True prepend: - description: Prepend each path entry. Useful to add the initial I(var) name. + description: + - Prepend each path entry. Useful to add the initial I(var) name. type: str required: False wantlist: - description: > - If set to I(True), the return value will always be a list. - This can also be accomplished using C(query) or B(q) instead of C(lookup). - U(https://docs.ansible.com/ansible/latest/plugins/lookup.html) + description: + - If set to I(True), the return value will always be a list. + - This can also be accomplished using C(query) or B(q) instead of C(lookup). + - U(https://docs.ansible.com/ansible/latest/plugins/lookup.html) type: bool notes: @@ -141,8 +143,10 @@ class LookupModule(LookupBase): keys = ["var", "prepend"] terms = dict(zip(keys, terms)) terms.update(kwargs) + + schema = [v for k, v in globals() if k.lower() == "documentation"] aav = AnsibleArgSpecValidator( - data=terms, schema=DOCUMENTATION, name="to_paths" + data=terms, schema=schema[0], name="to_paths" ) valid, errors, updated_data = aav.validate() if not valid: diff --git a/plugins/lookup/validate.py b/plugins/lookup/validate.py index 1d54b18..248f10e 100644 --- a/plugins/lookup/validate.py +++ b/plugins/lookup/validate.py @@ -13,47 +13,47 @@ DOCUMENTATION = """ version_added: "1.0.0" short_description: Validate data with provided criteria description: - - Validate I(data) with provided I(criteria) based on the validation I(engine). + - Validate I(data) with provided I(criteria) based on the validation I(engine). options: data: type: raw description: - - Data that will be validated against I(criteria). - - This option represents the value that is passed to the lookup plugin as the first argument. - For example C(lookup(config_data, config_criteria, engine='ansible.utils.jsonschema')), - in this case C(config_data) represents this option. - - For the type of I(data) that represents this value refer to the documentation of individual validate plugins. + - Data that will be validated against I(criteria). + - This option represents the value that is passed to the lookup plugin as the first argument. + For example C(lookup(config_data, config_criteria, engine='ansible.utils.jsonschema')), + in this case C(config_data) represents this option. + - For the type of I(data) that represents this value refer to the documentation of individual validate plugins. required: True criteria: type: raw description: - - The criteria used for validation of value that represents I(data) options. - - This option represents the second argument passed in the lookup plugin - For example C(lookup(config_data, config_criteria, engine='ansible.utils.jsonschema')), - in this case the value of C(config_criteria) represents this option. - - For the type of I(criteria) that represents this value refer to the documentation of individual - validate plugins. + - The criteria used for validation of value that represents I(data) options. + - This option represents the second argument passed in the lookup plugin + For example C(lookup(config_data, config_criteria, engine='ansible.utils.jsonschema')), + in this case the value of C(config_criteria) represents this option. + - For the type of I(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. - 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.utils.jsonschema) will be used. - - The value should be in fully qualified collection name format that is - C(..). + - The name of the validate plugin to use. + - 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.utils.jsonschema) will be used. + - The value should be in fully qualified collection name format that is + C(..). default: ansible.utils.jsonschema notes: - - For the type of options I(data) and I(criteria) refer to the individual validate plugin - documentation that is represented in the value of I(engine) option. - - For additional plugin configuration options refer to the individual validate plugin - documentation that is represented by the value of I(engine) option. - - The plugin configuration option can be either passed as C(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 C(key=value) pairs followed by task variables followed by environment variables. + - For the type of options I(data) and I(criteria) refer to the individual validate plugin + documentation that is represented in the value of I(engine) option. + - For additional plugin configuration options refer to the individual validate plugin + documentation that is represented by the value of I(engine) option. + - The plugin configuration option can be either passed as C(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 C(key=value) pairs followed by task variables followed by environment variables. """ EXAMPLES = r""" @@ -109,9 +109,12 @@ class LookupModule(LookupBase): if kwargs.get("engine"): params.update({"engine": kwargs["engine"]}) + schema = [ + v for k, v in globals().items() if k.lower() == "documentation" + ] valid, argspec_result, updated_params = check_argspec( - DOCUMENTATION, - "validate lookup", + schema=schema[0], + name="validate lookup", schema_conditionals=ARGSPEC_CONDITIONALS, **params )