Merging upstream version 2.17.0.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 23 insertions, 15 deletions

diff --git a/lib/ansible/modules/expect.py b/lib/ansible/modules/expect.py
index 8ff5cb4..6144763 100644
--- a/lib/ansible/modules/expect.py
+++ b/lib/ansible/modules/expect.py
@@ -3,8 +3,7 @@
 # (c) 2015, Matt Martz <matt@sivel.net>
 # 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
+from __future__ import annotations
 
 
 DOCUMENTATION = r'''
@@ -38,9 +37,11 @@ options:
   responses:
     type: dict
     description:
-      - Mapping of expected string/regex and string to respond with. If the
-        response is a list, successive matches return successive
-        responses. List functionality is new in 2.1.
+      - Mapping of prompt regular expressions and corresponding answer(s).
+      - Each key in O(responses) is a Python regex U(https://docs.python.org/3/library/re.html#regular-expression-syntax).
+      - The value of each key is a string or list of strings.
+        If the value is a string and the prompt is encountered multiple times, the answer will be repeated.
+        Provide the value as a list to give different answers for successive matches.
     required: true
   timeout:
     type: raw
@@ -69,15 +70,10 @@ notes:
   - If you want to run a command through the shell (say you are using C(<),
     C(>), C(|), and so on), you must specify a shell in the command such as
     C(/bin/bash -c "/path/to/something | grep else").
-  - The question, or key, under O(responses) is a python regex match. Case
-    insensitive searches are indicated with a prefix of C(?i).
+  - Case insensitive searches are indicated with a prefix of C(?i).
   - The C(pexpect) library used by this module operates with a search window
     of 2000 bytes, and does not use a multiline regex match. To perform a
     start of line bound match, use a pattern like ``(?m)^pattern``
-  - By default, if a question is encountered multiple times, its string
-    response will be repeated. If you need different responses for successive
-    question matches, instead of a string response, use a list of strings as
-    the response. The list functionality is new in 2.1.
   - The M(ansible.builtin.expect) module is designed for simple scenarios.
     For more complex needs, consider the use of expect code with the M(ansible.builtin.shell)
     or M(ansible.builtin.script) modules. (An example is part of the M(ansible.builtin.shell) module documentation).
@@ -98,14 +94,28 @@ EXAMPLES = r'''
   # you don't want to show passwords in your logs
   no_log: true
 
-- name: Generic question with multiple different responses
+- name: Match multiple regular expressions and demonstrate individual and repeated responses
   ansible.builtin.expect:
     command: /path/to/custom/command
     responses:
       Question:
+        # give a unique response for each of the 3 hypothetical prompts matched
         - response1
         - response2
         - response3
+      # give the same response for every matching prompt
+      "^Match another prompt$": "response"
+
+- name: Multiple questions with responses
+  ansible.builtin.expect:
+    command: /path/to/custom/command
+    responses:
+        "Please provide your name":
+            - "Anna"
+        "Database user":
+            - "{{ db_username }}"
+        "Database password":
+            - "{{ db_password }}"
 '''
 
 import datetime
@@ -167,9 +177,7 @@ def main():
         try:
             timeout = check_type_int(timeout)
         except TypeError as te:
-            module.fail_json(
-                msg="argument 'timeout' is of type {timeout_type} and we were unable to convert to int: {te}".format(timeout_type=type(timeout), te=te)
-            )
+            module.fail_json(msg=f"argument 'timeout' is of type {type(timeout)} and we were unable to convert to int: {te}")
     echo = module.params['echo']
 
     events = dict()