Add collection_version lookup (#3633)

* Add collection_verison lookup plugin.

* Document ansible-base 2.10 and ansible-core 2.11 special case.

* Add default for result_not_found.

* Simplify not existing test.

* Move metadata loading to function.

* Update plugins/lookup/collection_version.py

Co-authored-by: Brian Scholer <1260690+briantist@users.noreply.github.com>

* Extend tests.

* Fix tests for ansible-core < 2.12.

Co-authored-by: Brian Scholer <1260690+briantist@users.noreply.github.com>

tests/integration/targets/lookup_collection_version/aliases

@@ -0,0 +1 @@
+shippable/posix/group3

tests/integration/targets/lookup_collection_version/collections/ansible_collections/testns/testcoll/galaxy.yml

@@ -0,0 +1,7 @@
+namespace: testns
+name: testcoll
+version: 0.0.1
+authors:
+  - Ansible (https://github.com/ansible)
+description: null
+tags: [community]

tests/integration/targets/lookup_collection_version/collections/ansible_collections/testns/testcoll/plugins/modules/collection_module.py

@@ -0,0 +1,32 @@
+#!/usr/bin/python
+# -*- coding: utf-8 -*-
+
+# (c) 2021, Felix Fontein <felix@fontein.de>
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+DOCUMENTATION = '''
+---
+module: collection_module
+short_description: Test collection module
+description:
+  - This is a test module in a local collection.
+author: "Felix Fontein (@felixfontein)"
+options: {}
+'''
+
+EXAMPLES = ''' # '''
+
+RETURN = ''' # '''
+
+from ansible.module_utils.basic import AnsibleModule
+
+
+def main():
+    AnsibleModule(argument_spec={}).exit_json()
+
+
+if __name__ == '__main__':
+    main()

tests/integration/targets/lookup_collection_version/collections/ansible_collections/testns/testcoll_mf/FILES.json

@@ -0,0 +1,40 @@
+{
+ "files": [
+  {
+   "name": ".",
+   "ftype": "dir",
+   "chksum_type": null,
+   "chksum_sha256": null,
+   "format": 1
+  },
+  {
+   "name": "README.md",
+   "ftype": "file",
+   "chksum_type": "sha256",
+   "chksum_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
+   "format": 1
+  },
+  {
+   "name": "plugins",
+   "ftype": "dir",
+   "chksum_type": null,
+   "chksum_sha256": null,
+   "format": 1
+  },
+  {
+   "name": "plugins/modules",
+   "ftype": "dir",
+   "chksum_type": null,
+   "chksum_sha256": null,
+   "format": 1
+  },
+  {
+   "name": "plugins/modules/collection_module.py",
+   "ftype": "file",
+   "chksum_type": "sha256",
+   "chksum_sha256": "c3f0114d080c409c58c8846be8da7b91137b38eaf2d24f72a4a61a303f925f4d",
+   "format": 1
+  }
+ ],
+ "format": 1
+}

tests/integration/targets/lookup_collection_version/collections/ansible_collections/testns/testcoll_mf/MANIFEST.json

@@ -0,0 +1,30 @@
+{
+ "collection_info": {
+  "namespace": "testns",
+  "name": "testcoll_mf",
+  "version": "0.0.1",
+  "authors": [
+   "Ansible (https://github.com/ansible)"
+  ],
+  "readme": "README.md",
+  "tags": [
+   "community"
+  ],
+  "description": null,
+  "license": [],
+  "license_file": null,
+  "dependencies": {},
+  "repository": null,
+  "documentation": null,
+  "homepage": null,
+  "issues": null
+ },
+ "file_manifest_file": {
+  "name": "FILES.json",
+  "ftype": "file",
+  "chksum_type": "sha256",
+  "chksum_sha256": "025818f18fcae5c9f78d778ae6e246ecffed6d56a886ffbc145cb66d54e9951e",
+  "format": 1
+ },
+ "format": 1
+}

tests/integration/targets/lookup_collection_version/collections/ansible_collections/testns/testcoll_mf/plugins/modules/collection_module.py

@@ -0,0 +1,32 @@
+#!/usr/bin/python
+# -*- coding: utf-8 -*-
+
+# (c) 2021, Felix Fontein <felix@fontein.de>
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+DOCUMENTATION = '''
+---
+module: collection_module
+short_description: Test collection module
+description:
+  - This is a test module in a local collection.
+author: "Felix Fontein (@felixfontein)"
+options: {}
+'''
+
+EXAMPLES = ''' # '''
+
+RETURN = ''' # '''
+
+from ansible.module_utils.basic import AnsibleModule
+
+
+def main():
+    AnsibleModule(argument_spec={}).exit_json()
+
+
+if __name__ == '__main__':
+    main()

tests/integration/targets/lookup_collection_version/collections/ansible_collections/testns/testcoll_nothing/plugins/modules/collection_module.py

@@ -0,0 +1,32 @@
+#!/usr/bin/python
+# -*- coding: utf-8 -*-
+
+# (c) 2021, Felix Fontein <felix@fontein.de>
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+DOCUMENTATION = '''
+---
+module: collection_module
+short_description: Test collection module
+description:
+  - This is a test module in a local collection.
+author: "Felix Fontein (@felixfontein)"
+options: {}
+'''
+
+EXAMPLES = ''' # '''
+
+RETURN = ''' # '''
+
+from ansible.module_utils.basic import AnsibleModule
+
+
+def main():
+    AnsibleModule(argument_spec={}).exit_json()
+
+
+if __name__ == '__main__':
+    main()

tests/integration/targets/lookup_collection_version/collections/ansible_collections/testns/testcoll_nv/galaxy.yml

@@ -0,0 +1,6 @@
+namespace: testns
+name: testcoll_nv
+authors:
+  - Ansible (https://github.com/ansible)
+description: null
+tags: [community]

tests/integration/targets/lookup_collection_version/collections/ansible_collections/testns/testcoll_nv/plugins/modules/collection_module.py

@@ -0,0 +1,32 @@
+#!/usr/bin/python
+# -*- coding: utf-8 -*-
+
+# (c) 2021, Felix Fontein <felix@fontein.de>
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+DOCUMENTATION = '''
+---
+module: collection_module
+short_description: Test collection module
+description:
+  - This is a test module in a local collection.
+author: "Felix Fontein (@felixfontein)"
+options: {}
+'''
+
+EXAMPLES = ''' # '''
+
+RETURN = ''' # '''
+
+from ansible.module_utils.basic import AnsibleModule
+
+
+def main():
+    AnsibleModule(argument_spec={}).exit_json()
+
+
+if __name__ == '__main__':
+    main()

tests/integration/targets/lookup_collection_version/library/local_module.py

@@ -0,0 +1,32 @@
+#!/usr/bin/python
+# -*- coding: utf-8 -*-
+
+# (c) 2021, Felix Fontein <felix@fontein.de>
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+DOCUMENTATION = '''
+---
+module: local_module
+short_description: Test local module
+description:
+  - This is a test module locally next to a playbook.
+author: "Felix Fontein (@felixfontein)"
+options: {}
+'''
+
+EXAMPLES = ''' # '''
+
+RETURN = ''' # '''
+
+from ansible.module_utils.basic import AnsibleModule
+
+
+def main():
+    AnsibleModule(argument_spec={}).exit_json()
+
+
+if __name__ == '__main__':
+    main()

tests/integration/targets/lookup_collection_version/runme.sh

@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+
+set -eux
+
+export ANSIBLE_TEST_PREFER_VENV=1  # see https://github.com/ansible/ansible/pull/73000#issuecomment-757012395; can be removed once Ansible 2.9 and ansible-base 2.10 support has been dropped
+source virtualenv.sh
+
+# The collection loader ignores paths which have more than one ansible_collections in it.
+# That's why we have to copy this directory to a temporary place and run the test there.
+
+# Create temporary folder
+TEMPDIR=$(mktemp -d)
+trap '{ rm -rf ${TEMPDIR}; }' EXIT
+
+cp -r . "${TEMPDIR}"
+cd "${TEMPDIR}"
+
+ansible-playbook runme.yml "$@"

tests/integration/targets/lookup_collection_version/runme.yml

@@ -0,0 +1,35 @@
+- hosts: localhost
+  tasks:
+    - name: Test collection_version
+      assert:
+        that:
+          # Collection that does not exist
+          - query('community.general.collection_version', 'foo.bar') == [none]
+          - lookup('community.general.collection_version', 'foo.bar', result_not_found='foo') == 'foo'
+          # Collection that exists
+          - lookup('community.general.collection_version', 'community.general') is string
+          # Local collection
+          - lookup('community.general.collection_version', 'testns.testcoll') == '0.0.1'
+          # Local collection with no version
+          - lookup('community.general.collection_version', 'testns.testcoll_nv') == '*'
+          - lookup('community.general.collection_version', 'testns.testcoll_nv', result_no_version='') == ''
+          # Local collection with MANIFEST.json
+          - lookup('community.general.collection_version', 'testns.testcoll_mf') == '0.0.1'
+          # Local collection with no galaxy.yml and no MANIFEST.json
+          - lookup('community.general.collection_version', 'testns.testcoll_nothing') == '*'
+          - lookup('community.general.collection_version', 'testns.testcoll_nothing', result_no_version='0.0.0') == '0.0.0'
+          # Multiple collection names at once
+          - lookup('community.general.collection_version', 'testns.testcoll', 'testns.testcoll_nv', 'testns.testcoll_nv', 'testns.testcoll_mf', 'foo.bar')
+            == ['0.0.1', '*', '*', '0.0.1', none]
+
+    - name: Invalid FQCN
+      set_fact:
+        test: "{{ query('community.general.collection_version', 'foo.bar.baz') }}"
+      ignore_errors: true
+      register: invalid_fqcn
+
+    - name: Validate error message
+      assert:
+        that:
+          - >
+            '"foo.bar.baz" is not a FQCN' in invalid_fqcn.msg