Fix 'sequence' lookup shortcut syntax and documentation (#22989)

* fix 'sequence' lookup shortcut syntax and documentation

* Update playbooks_loops.rst

Minor edits for grammar and clarity.

* Update playbooks_loops.rst

Another tweak for clarity.

docs/docsite/rst/playbooks_loops.rst

@@ -277,10 +277,12 @@ The authorized_key pattern is exactly where it comes up most.
 Looping over Integer Sequences
 ``````````````````````````````
 
-``with_sequence`` generates a sequence of items in ascending numerical order. You
+``with_sequence`` generates a sequence of items. You
-can specify a start, end, and an optional step value.
+can specify a start value, an end value, an optional "stride" value that specifies the number of steps to increment the sequence, and an optional printf-style format string.
 
-Arguments should be specified in key=value pairs.  If supplied, the 'format' is a printf style string.
+Arguments should be specified as key=value pair strings.
+
+A simple shortcut form of the arguments string is also accepted: ``[start-]end[/stride][:format]``.
 
 Numerical values can be specified in decimal, hexadecimal (0x3f8) or octal (0600).
 Negative numbers are not supported.  This works as follows::
@@ -303,27 +305,20 @@ Negative numbers are not supported.  This works as follows::
             name: "{{ item }}"
             state: present
             groups: "evens"
-          with_sequence:
+          with_sequence: start=0 end=32 format=testuser%02x
-            - start: 0
-            - end: 32
-            - format: testuser%02x
 
         # create a series of directories with even numbers for some reason
         - file:
             dest: "/var/stuff/{{ item }}"
             state: directory
-          with_sequence:
+          with_sequence: start=4 end=16 stride=2
-            - start: 4
-            - end: 16
-            - stride: 2
 
         # a simpler way to use the sequence plugin
         # create 4 groups
         - group:
             name: "group{{ item }}"
             state: present
-          with_sequence:
+          with_sequence: count=4
-            count: 4
 
 .. _random_choice:
 

lib/ansible/plugins/lookup/sequence.py

@@ -142,6 +142,8 @@ class LookupModule(LookupBase):
         if format is not None:
             self.format = format
 
+        return True
+
     def sanity_check(self):
         if self.count is None and self.end is None:
             raise AnsibleError( "must specify count or end in with_sequence")

test/integration/targets/iterators/tasks/main.yml

@@ -97,6 +97,29 @@
         - count_of_zero | skipped
         - not count_of_one | skipped
 
+- name: test with_sequence shortcut syntax (end)
+  set_fact: "{{ 'ws_z_' + item }}={{ item }}"
+  with_sequence: '4'
+
+- name: test with_sequence shortcut syntax (start-end/stride)
+  set_fact: "{{ 'ws_z_' + item }}=stride_{{ item }}"
+  with_sequence: '2-6/2'
+
+- name: test with_sequence shortcut syntax (start-end:format)
+  set_fact: "{{ 'ws_z_' + item }}={{ item }}"
+  with_sequence: '7-8:host%02d'
+
+- name: verify with_sequence shortcut syntax
+  assert:
+    that:
+        - "ws_z_1 == '1'"
+        - "ws_z_2 == 'stride_2'"
+        - "ws_z_3 == '3'"
+        - "ws_z_4 == 'stride_4'"
+        - "ws_z_6 == 'stride_6'"
+        - "ws_z_host07 == 'host07'"
+        - "ws_z_host08 == 'host08'"
+
 # WITH_RANDOM_CHOICE
 
 - name: test with_random_choice
@@ -159,7 +182,7 @@
         - "_xl == 'l'"
 
 
-# WITH_TOGETHER        
+# WITH_TOGETHER
 
 - name: test with_together
   #shell: echo {{ item }}
@@ -201,14 +224,14 @@
 - name: verify with_first_found results
   assert:
     that:
-        - "first_found == first_expected"  
+        - "first_found == first_expected"
         - "first_found != first_unexpected"
 
 # WITH_LINES
 
 - name: test with_lines
   #shell: echo "{{ item }}"
-  set_fact: "{{ item }}=set" 
+  set_fact: "{{ item }}=set"
   with_lines: for i in $(seq 1 5); do echo "l$i" ; done;
 
 - name: verify with_lines results
@@ -244,7 +267,7 @@
   set_fact: "{{ item }}=flattened"
   with_flattened:
     - [ 'a__' ]
-    - [ 'b__', ['c__', 'd__'] ]        
+    - [ 'b__', ['c__', 'd__'] ]
 
 - name: verify with_flattened results
   assert: