diff --git a/changelogs/fragments/argument-spec-context.yml b/changelogs/fragments/argument-spec-context.yml new file mode 100644 index 00000000000..985a2050dd8 --- /dev/null +++ b/changelogs/fragments/argument-spec-context.yml @@ -0,0 +1,4 @@ +minor_changes: +- module argument spec - Allow module authors to include arbitrary additional context in the argument spec, by making use of a new top level key + called ``context``. This key should be a dict type. This allows for users to customize what they place in the argument spec, without having to + ignore sanity tests that validate the schema. diff --git a/test/integration/targets/ansible-test-sanity-validate-modules/ansible_collections/ns/col/plugins/modules/invalid_argument_spec_extra_key.py b/test/integration/targets/ansible-test-sanity-validate-modules/ansible_collections/ns/col/plugins/modules/invalid_argument_spec_extra_key.py new file mode 100644 index 00000000000..04807a1ee16 --- /dev/null +++ b/test/integration/targets/ansible-test-sanity-validate-modules/ansible_collections/ns/col/plugins/modules/invalid_argument_spec_extra_key.py @@ -0,0 +1,36 @@ +#!/usr/bin/python +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) + +from __future__ import annotations + +DOCUMENTATION = ''' +module: invalid_argument_spec_extra_key +short_description: Invalid argument spec extra key schema test module +description: Invalid argument spec extra key schema test module +author: + - Ansible Core Team +options: + foo: + description: foo + type: str +''' + +EXAMPLES = '''#''' +RETURN = '''''' + +from ansible.module_utils.basic import AnsibleModule + + +def main(): + AnsibleModule( + argument_spec=dict( + foo=dict( + type='str', + extra_key='bar', + ), + ), + ) + + +if __name__ == '__main__': + main() diff --git a/test/integration/targets/ansible-test-sanity-validate-modules/ansible_collections/ns/col/plugins/modules/invalid_argument_spec_incorrect_context.py b/test/integration/targets/ansible-test-sanity-validate-modules/ansible_collections/ns/col/plugins/modules/invalid_argument_spec_incorrect_context.py new file mode 100644 index 00000000000..6e3d2441346 --- /dev/null +++ b/test/integration/targets/ansible-test-sanity-validate-modules/ansible_collections/ns/col/plugins/modules/invalid_argument_spec_incorrect_context.py @@ -0,0 +1,36 @@ +#!/usr/bin/python +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) + +from __future__ import annotations + +DOCUMENTATION = ''' +module: invalid_argument_spec_incorrect_context +short_description: Invalid argument spec incorrect context schema test module +description: Invalid argument spec incorrect context schema test module +author: + - Ansible Core Team +options: + foo: + description: foo + type: str +''' + +EXAMPLES = '''#''' +RETURN = '''''' + +from ansible.module_utils.basic import AnsibleModule + + +def main(): + AnsibleModule( + argument_spec=dict( + foo=dict( + type='str', + context='bar', + ), + ), + ) + + +if __name__ == '__main__': + main() diff --git a/test/integration/targets/ansible-test-sanity-validate-modules/ansible_collections/ns/col/plugins/modules/valid_argument_spec_context.py b/test/integration/targets/ansible-test-sanity-validate-modules/ansible_collections/ns/col/plugins/modules/valid_argument_spec_context.py new file mode 100644 index 00000000000..2aa67abd19a --- /dev/null +++ b/test/integration/targets/ansible-test-sanity-validate-modules/ansible_collections/ns/col/plugins/modules/valid_argument_spec_context.py @@ -0,0 +1,38 @@ +#!/usr/bin/python +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) + +from __future__ import annotations + +DOCUMENTATION = ''' +module: valid_argument_spec_context +short_description: Valid argument spec context schema test module +description: Valid argument spec context schema test module +author: + - Ansible Core Team +options: + foo: + description: foo + type: str +''' + +EXAMPLES = '''#''' +RETURN = '''''' + +from ansible.module_utils.basic import AnsibleModule + + +def main(): + AnsibleModule( + argument_spec=dict( + foo=dict( + type='str', + context=dict( + extra_key='bar', + ), + ), + ), + ) + + +if __name__ == '__main__': + main() diff --git a/test/integration/targets/ansible-test-sanity-validate-modules/expected.txt b/test/integration/targets/ansible-test-sanity-validate-modules/expected.txt index ef805f4a703..ad3e79fd3b0 100644 --- a/test/integration/targets/ansible-test-sanity-validate-modules/expected.txt +++ b/test/integration/targets/ansible-test-sanity-validate-modules/expected.txt @@ -4,6 +4,8 @@ plugins/modules/check_mode_attribute_2.py:0:0: attributes-check-mode: The module plugins/modules/check_mode_attribute_3.py:0:0: attributes-check-mode: The module does declare support for check mode, but the check_mode attribute's support value is 'none' plugins/modules/check_mode_attribute_4.py:0:0: attributes-check-mode-details: The module declares it does not fully support check mode, but has no details on what exactly that means plugins/modules/import_order.py:7:0: import-before-documentation: Import found before documentation variables. All imports must appear below DOCUMENTATION/EXAMPLES/RETURN. +plugins/modules/invalid_argument_spec_extra_key.py:0:0: invalid-ansiblemodule-schema: AnsibleModule.argument_spec.foo.extra_key: extra keys not allowed @ data['argument_spec']['foo']['extra_key']. Got 'bar' +plugins/modules/invalid_argument_spec_incorrect_context.py:0:0: invalid-ansiblemodule-schema: AnsibleModule.argument_spec.foo.context: expected dict for dictionary value @ data['argument_spec']['foo']['context']. Got 'bar' plugins/modules/invalid_choice_value.py:0:0: doc-choices-do-not-match-spec: Argument 'caching' in argument_spec defines choices as (['ReadOnly', 'ReadOnly']) but documentation defines choices as (['ReadOnly', 'ReadWrite']) plugins/modules/invalid_yaml_syntax.py:0:0: deprecation-mismatch: "meta/runtime.yml" and DOCUMENTATION.deprecation do not agree. plugins/modules/invalid_yaml_syntax.py:0:0: missing-documentation: No DOCUMENTATION provided diff --git a/test/lib/ansible_test/_util/controller/sanity/validate-modules/validate_modules/schema.py b/test/lib/ansible_test/_util/controller/sanity/validate-modules/validate_modules/schema.py index 3f705525456..ba4e1883fb3 100644 --- a/test/lib/ansible_test/_util/controller/sanity/validate-modules/validate_modules/schema.py +++ b/test/lib/ansible_test/_util/controller/sanity/validate-modules/validate_modules/schema.py @@ -297,6 +297,7 @@ def argument_spec_schema(for_collection): [is_callable, list_string_types], ), 'choices': Any([object], (object,)), + 'context': dict, 'required': bool, 'no_log': bool, 'aliases': Any(list_string_types, tuple(list_string_types)),