Make lookup plugins return lists to fix failures (#15625)

* Make lookup plugins return lists to fix failures

* Update unit tests

* Use lookup for test failures, update docs

* Grammar fix from review

Co-authored-by: Sviatoslav Sydorenko (Святослав Сидоренко) <wk.cvs.github@sydorenko.org.ua>

---------

Co-authored-by: Sviatoslav Sydorenko (Святослав Сидоренко) <wk.cvs.github@sydorenko.org.ua>

awx_collection/README.md

@@ -32,33 +32,11 @@ Installing the `tar.gz` involves no special instructions.
 ## Running
 
 Non-deprecated modules in this collection have no Python requirements, but
-may require the official [AWX CLI](https://pypi.org/project/awxkit/)
+may require the AWX CLI
 in the future. The `DOCUMENTATION` for each module will report this.
 
-You can specify authentication by a combination of either:
+You can specify authentication by host, username, and password.
 
- - host, username, password
- - host, OAuth2 token
-
-The OAuth2 token is the preferred method. You can obtain a token via the
-``login`` command with the AWX CLI.
-
-These can be specified via (from highest to lowest precedence):
-
- - direct module parameters
- - environment variables (most useful when running against localhost)
- - a config file path specified by the `tower_config_file` parameter
- - a config file at `~/.tower_cli.cfg`
- - a config file at `/etc/tower/tower_cli.cfg`
-
-Config file syntax looks like this:
-
-```
-[general]
-host = https://localhost:8043
-verify_ssl = true
-oauth_token = LEdCpKVKc4znzffcpQL5vLG8oyeku6
-```
 
 ## Release and Upgrade Notes
 
@@ -101,6 +79,7 @@ The following notes are changes that may require changes to playbooks:
  - The `notification_configuration` parameter of `tower_notification_template` has changed from a string to a dict. Please use the `lookup` plugin to read an existing file into a dict.
  - `tower_credential` no longer supports passing a file name to `ssh_key_data`.
  - The HipChat `notification_type` has been removed and can no longer be created using the `tower_notification_template` module.
+ - Lookup plugins now always return a list, and if you want a scalar value use `lookup` as opposed to `query`
 
 ## Running Unit Tests
 

awx_collection/plugins/lookup/schedule_rrule.py

@@ -75,7 +75,7 @@ DOCUMENTATION = """
 EXAMPLES = """
     - name: Create a string for a schedule
       debug:
-        msg: "{{ query('awx.awx.schedule_rrule', 'none', start_date='1979-09-13 03:45:07') }}"
+        msg: "{{ lookup('awx.awx.schedule_rrule', 'none', start_date='1979-09-13 03:45:07') }}"
 """
 
 RETURN = """
@@ -237,4 +237,4 @@ class LookupModule(LookupBase):
         if kwargs.get('every', 1) == 1:
             return_rrule = "{0};INTERVAL=1".format(return_rrule)
 
-        return return_rrule
+        return [return_rrule]

awx_collection/plugins/lookup/schedule_rruleset.py

@@ -109,7 +109,7 @@ DOCUMENTATION = """
 EXAMPLES = """
     - name: Create a ruleset for everyday except Sundays
       set_fact:
-        complex_rule: "{{ query(awx.awx.schedule_rruleset, '2022-04-30 10:30:45', rules=rrules, timezone='UTC' ) }}"
+        complex_rule: "{{ lookup(awx.awx.schedule_rruleset, '2022-04-30 10:30:45', rules=rrules, timezone='UTC' ) }}"
       vars:
         rrules:
           - frequency: 'day'
@@ -352,4 +352,4 @@ class LookupModule(LookupBase):
             raise_from(AnsibleError("Failed to parse generated rule set via rruleset {0}".format(e)), e)
 
         # return self.get_rrule(frequency, kwargs)
-        return rruleset_str
+        return [rruleset_str]

awx_collection/test/awx/test_schedule.py

@@ -82,7 +82,7 @@ def test_delete_same_named_schedule(run_module, project, inventory, admin_user):
 )
 def test_rrule_lookup_plugin(collection_import, freq, kwargs, expect):
     LookupModule = collection_import('plugins.lookup.schedule_rrule').LookupModule()
-    generated_rule = LookupModule.get_rrule(freq, kwargs)
+    generated_rule = LookupModule.get_rrule(freq, kwargs)[0]
     assert generated_rule == expect
     rrule_checker = SchedulePreviewSerializer()
     # Try to run our generated rrule through the awx validator
@@ -99,7 +99,7 @@ def test_empty_schedule_rrule(collection_import, freq):
         pfreq = 'DAILY;COUNT=1'
     else:
         pfreq = freq.upper() + 'LY'
-    assert LookupModule.get_rrule(freq, {}).endswith(' RRULE:FREQ={0};INTERVAL=1'.format(pfreq))
+    assert LookupModule.get_rrule(freq, {})[0].endswith(' RRULE:FREQ={0};INTERVAL=1'.format(pfreq))
 
 
 @pytest.mark.parametrize(

awx_collection/tests/integration/targets/lookup_rruleset/tasks/main.yml

@@ -11,7 +11,7 @@
 
 - name: Call ruleset with no rules
   set_fact:
-    complex_rule: "{{ query(ruleset_plugin_name | string, '2022-04-30 10:30:45') }}"
+    complex_rule: "{{ lookup(ruleset_plugin_name | string, '2022-04-30 10:30:45') }}"
   ignore_errors: True
   register: results
 
@@ -23,7 +23,7 @@
 
 - name: call ruleset with a missing frequency
   set_fact:
-    complex_rule: "{{ query(ruleset_plugin_name, '2022-04-30 10:30:45', rules=rrules ) }}"
+    complex_rule: "{{ lookup(ruleset_plugin_name, '2022-04-30 10:30:45', rules=rrules ) }}"
   ignore_errors: True
   register: results
   vars:
@@ -41,7 +41,7 @@
 
 - name: call ruleset with a missing frequency
   set_fact:
-    complex_rule: "{{ query(ruleset_plugin_name, '2022-04-30 10:30:45', rules=rrules ) }}"
+    complex_rule: "{{ lookup(ruleset_plugin_name, '2022-04-30 10:30:45', rules=rrules ) }}"
   ignore_errors: True
   register: results
   vars:
@@ -59,7 +59,7 @@
 
 - name: call rruleset with an invalid frequency
   set_fact:
-    complex_rule: "{{ query(ruleset_plugin_name, '2022-04-30 10:30:45', rules=rrules ) }}"
+    complex_rule: "{{ lookup(ruleset_plugin_name, '2022-04-30 10:30:45', rules=rrules ) }}"
   ignore_errors: True
   register: results
   vars:
@@ -78,7 +78,7 @@
 
 - name: call rruleset with an invalid end_on
   set_fact:
-    complex_rule: "{{ query(ruleset_plugin_name, '2022-04-30 10:30:45', rules=rrules ) }}"
+    complex_rule: "{{ lookup(ruleset_plugin_name, '2022-04-30 10:30:45', rules=rrules ) }}"
   ignore_errors: True
   register: results
   vars:
@@ -97,7 +97,7 @@
 
 - name: Every Mondays
   set_fact:
-    complex_rule: "{{ query(ruleset_plugin_name, '2022-04-30 10:30:45', rules=rrules, timezone='UTC' ) }}"
+    complex_rule: "{{ lookup(ruleset_plugin_name, '2022-04-30 10:30:45', rules=rrules, timezone='UTC' ) }}"
   ignore_errors: True
   register: results
   vars:
@@ -114,7 +114,7 @@
 
 - name: call rruleset with an invalid byweekday
   set_fact:
-    complex_rule: "{{ query(ruleset_plugin_name, '2022-04-30 10:30:45', rules=rrules ) }}"
+    complex_rule: "{{ lookup(ruleset_plugin_name, '2022-04-30 10:30:45', rules=rrules ) }}"
   ignore_errors: True
   register: results
   vars:
@@ -133,7 +133,7 @@
 
 - name: call rruleset with a monthly rule with invalid bymonthday (a)
   set_fact:
-    complex_rule: "{{ query(ruleset_plugin_name, '2022-04-30 10:30:45', rules=rrules ) }}"
+    complex_rule: "{{ lookup(ruleset_plugin_name, '2022-04-30 10:30:45', rules=rrules ) }}"
   ignore_errors: True
   register: results
   vars:
@@ -152,7 +152,7 @@
 
 - name: call rruleset with a monthly rule with invalid bymonthday (-1)
   set_fact:
-    complex_rule: "{{ query(ruleset_plugin_name, '2022-04-30 10:30:45', rules=rrules ) }}"
+    complex_rule: "{{ lookup(ruleset_plugin_name, '2022-04-30 10:30:45', rules=rrules ) }}"
   ignore_errors: True
   register: results
   vars:
@@ -171,7 +171,7 @@
 
 - name: call rruleset with a monthly rule with invalid bymonthday (32)
   set_fact:
-    complex_rule: "{{ query(ruleset_plugin_name, '2022-04-30 10:30:45', rules=rrules ) }}"
+    complex_rule: "{{ lookup(ruleset_plugin_name, '2022-04-30 10:30:45', rules=rrules ) }}"
   ignore_errors: True
   register: results
   vars:
@@ -190,7 +190,7 @@
 
 - name: call rruleset with a monthly rule with invalid bysetpos (junk)
   set_fact:
-    complex_rule: "{{ query(ruleset_plugin_name, '2022-04-30 10:30:45', rules=rrules ) }}"
+    complex_rule: "{{ lookup(ruleset_plugin_name, '2022-04-30 10:30:45', rules=rrules ) }}"
   ignore_errors: True
   register: results
   vars:
@@ -209,7 +209,7 @@
 
 - name: call rruleset with an invalid timezone
   set_fact:
-    complex_rule: "{{ query(ruleset_plugin_name, '2022-04-30 10:30:45', rules=rrules, timezone='junk' ) }}"
+    complex_rule: "{{ lookup(ruleset_plugin_name, '2022-04-30 10:30:45', rules=rrules, timezone='junk' ) }}"
   ignore_errors: True
   register: results
   vars:
@@ -228,7 +228,7 @@
 
 - name: call rruleset with only exclude rules
   set_fact:
-    complex_rule: "{{ query(ruleset_plugin_name, '2022-04-30 10:30:45', rules=rrules ) }}"
+    complex_rule: "{{ lookup(ruleset_plugin_name, '2022-04-30 10:30:45', rules=rrules ) }}"
   ignore_errors: True
   register: results
   vars:
@@ -249,7 +249,7 @@
 
 - name: Every day except for Sundays
   set_fact:
-    complex_rule: "{{ query(ruleset_plugin_name, '2022-04-30 10:30:45', rules=rrules, timezone='UTC' ) }}"
+    complex_rule: "{{ lookup(ruleset_plugin_name, '2022-04-30 10:30:45', rules=rrules, timezone='UTC' ) }}"
   ignore_errors: True
   register: results
   vars:
@@ -269,7 +269,7 @@
 
 - name: Every day except for April 30th
   set_fact:
-    complex_rule: "{{ query(ruleset_plugin_name, '2023-04-28 17:00:00', rules=rrules, timezone='UTC' ) }}"
+    complex_rule: "{{ lookup(ruleset_plugin_name, '2023-04-28 17:00:00', rules=rrules, timezone='UTC' ) }}"
   ignore_errors: True
   register: results
   vars:
@@ -290,7 +290,7 @@
 
 - name: Every 5 minutes but not on Mondays from 5-7pm
   set_fact:
-    complex_rule: "{{ query(ruleset_plugin_name, '2022-04-30 10:30:45', rules=rrules, timezone='UTC' ) }}"
+    complex_rule: "{{ lookup(ruleset_plugin_name, '2022-04-30 10:30:45', rules=rrules, timezone='UTC' ) }}"
   ignore_errors: True
   register: results
   vars:
@@ -313,7 +313,7 @@
 
 - name: Every 15 minutes Monday to Friday from 10:01am to 6:02pm (inclusive)
   set_fact:
-    complex_rule: "{{ query(ruleset_plugin_name, '2022-04-30 10:30:45', rules=rrules, timezone='UTC' ) }}"
+    complex_rule: "{{ lookup(ruleset_plugin_name, '2022-04-30 10:30:45', rules=rrules, timezone='UTC' ) }}"
   ignore_errors: True
   register: results
   vars:
@@ -342,7 +342,7 @@
 
 - name: Any Saturday whose month day is between 12 and 18
   set_fact:
-    complex_rule: "{{ query(ruleset_plugin_name, '2022-04-30 10:30:45', rules=rrules, timezone='UTC' ) }}"
+    complex_rule: "{{ lookup(ruleset_plugin_name, '2022-04-30 10:30:45', rules=rrules, timezone='UTC' ) }}"
   ignore_errors: True
   register: results
   vars:
@@ -359,7 +359,7 @@
 
 - name: mondays, Tuesdays, and WEDNESDAY with case-insensitivity
   set_fact:
-    complex_rule: "{{ query(ruleset_plugin_name, '2022-04-30 10:30:45', rules=rrules, timezone='UTC' ) }}"
+    complex_rule: "{{ lookup(ruleset_plugin_name, '2022-04-30 10:30:45', rules=rrules, timezone='UTC' ) }}"
   ignore_errors: True
   register: results
   vars:

awx_collection/tests/integration/targets/schedule_rrule/tasks/main.yml

@@ -9,7 +9,7 @@
 
 - name: Test too many params (failure from validation of terms)
   ansible.builtin.debug:
-    msg: "{{ query(plugin_name | string, 'none', 'weekly', start_date='2020-4-16 03:45:07') }}"
+    msg: "{{ lookup(plugin_name | string, 'none', 'weekly', start_date='2020-4-16 03:45:07') }}"
   ignore_errors: true
   register: result
 
@@ -20,7 +20,7 @@
 
 - name: Test invalid frequency (failure from validation of term)
   ansible.builtin.debug:
-    msg: "{{ query(plugin_name, 'john', start_date='2020-4-16 03:45:07') }}"
+    msg: "{{ lookup(plugin_name, 'john', start_date='2020-4-16 03:45:07') }}"
   ignore_errors: true
   register: result
 
@@ -31,7 +31,7 @@
 
 - name: Test an invalid start date (generic failure case from get_rrule)
   ansible.builtin.debug:
-    msg: "{{ query(plugin_name, 'none', start_date='invalid') }}"
+    msg: "{{ lookup(plugin_name, 'none', start_date='invalid') }}"
   ignore_errors: true
   register: result
 
@@ -42,7 +42,7 @@
 
 - name: Test end_on as count (generic success case)
   ansible.builtin.debug:
-    msg: "{{ query(plugin_name, 'minute', start_date='2020-4-16 03:45:07', end_on='2') }}"
+    msg: "{{ lookup(plugin_name, 'minute', start_date='2020-4-16 03:45:07', end_on='2') }}"
   register: result
 
 - ansible.builtin.assert:

awx_collection/tools/roles/template_galaxy/templates/README.md.j2

@@ -90,6 +90,7 @@ The following notes are changes that may require changes to playbooks:
  - The `notification_configuration` parameter of `tower_notification_template` has changed from a string to a dict. Please use the `lookup` plugin to read an existing file into a dict.
  - `tower_credential` no longer supports passing a file name to `ssh_key_data`.
  - The HipChat `notification_type` has been removed and can no longer be created using the `tower_notification_template` module.
+ - Lookup plugins now always reutrn a list, and if you want a scalar value use `lookup` as opposed to `query`
 
 {% if collection_package | lower() == "awx" %}
 ## Running Unit Tests