[PR #9893/9286b601 backport][stable-10] cmd_runner_fmt.as_fixed() now accepts list of args (#9915)

cmd_runner_fmt.as_fixed() now accepts list of args (#9893)

* cmd_runner_fmt.as_fixed() now accepts list of args

* update CmdRunner guide

* add changelog frag

* Update changelogs/fragments/9893-cmdrunner-as-fixed-args.yml

* fix overdoing in as_fixed()

(cherry picked from commit 9286b60182)

Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com>

changelogs/fragments/9893-cmdrunner-as-fixed-args.yml

@@ -0,0 +1,2 @@
+minor_changes:
+  - CmdRunner module utils - the convenience method ``cmd_runner_fmt.as_fixed()`` now accepts multiple arguments as a list (https://github.com/ansible-collections/community.general/pull/9893).

docs/docsite/rst/guide_cmdrunner.rst

@@ -267,24 +267,54 @@ In these descriptions ``value`` refers to the single parameter passed to the for
         +------------+-------------------------+
 
 - ``cmd_runner_fmt.as_fixed()``
-    This method receives one parameter ``arg``, the function expects no ``value`` - if one
+    This method defines one or more fixed arguments that are returned by the generated function
-    is provided then it is ignored.
+    regardless whether ``value`` is passed to it or not.
-    The function returns ``arg`` as-is.
 
-    - Creation:
+    This method accepts these arguments in one of three forms:
-        ``cmd_runner_fmt.as_fixed("--version")``
+
+        * one scalar parameter ``arg``, which will be returned as ``[arg]`` by the function, or
+        * one sequence parameter, such as a list, ``arg``, which will be returned by the function as ``arg[0]``, or
+        * multiple parameters ``args``, which will be returned as ``args`` directly by the function.
+
+    See the examples below for each one of those forms. And, stressing that the generated function expects no ``value`` - if one
+    is provided then it is ignored.
+
+    - Creation (one scalar argument):
+        * ``cmd_runner_fmt.as_fixed("--version")``
     - Examples:
-        +---------+-----------------------+
+        +---------+--------------------------------------+
-        | Value   | Outcome               |
+        | Value   | Outcome                              |
-        +=========+=======================+
+        +=========+======================================+
-        |         | ``["--version"]``     |
+        |         | * ``["--version"]``                  |
-        +---------+-----------------------+
+        +---------+--------------------------------------+
-        | 57      | ``["--version"]``     |
+        | 57      | * ``["--version"]``                  |
-        +---------+-----------------------+
+        +---------+--------------------------------------+
+
+    - Creation (one sequence argument):
+        * ``cmd_runner_fmt.as_fixed(["--list", "--json"])``
+    - Examples:
+        +---------+--------------------------------------+
+        | Value   | Outcome                              |
+        +=========+======================================+
+        |         | * ``["--list", "--json"]``           |
+        +---------+--------------------------------------+
+        | True    | * ``["--list", "--json"]``           |
+        +---------+--------------------------------------+
+
+    - Creation (multiple arguments):
+        * ``cmd_runner_fmt.as_fixed("--one", "--two", "--three")``
+    - Examples:
+        +---------+--------------------------------------+
+        | Value   | Outcome                              |
+        +=========+======================================+
+        |         | * ``["--one", "--two", "--three"]``  |
+        +---------+--------------------------------------+
+        | False   | * ``["--one", "--two", "--three"]``  |
+        +---------+--------------------------------------+
 
     - Note:
         This is the only special case in which a value can be missing for the formatting function.
-        The example also comes from the code in `Quickstart`_.
+        The first example here comes from the code in `Quickstart`_.
         In that case, the module has code to determine the command's version so that it can assert compatibility.
         There is no *value* to be passed for that CLI argument.
 

plugins/module_utils/cmd_runner_fmt.py

@@ -78,7 +78,9 @@ def as_list(ignore_none=None, min_len=0, max_len=None):
     return _ArgFormat(func, ignore_none=ignore_none)
 
 
-def as_fixed(args):
+def as_fixed(*args):
+    if len(args) == 1 and is_sequence(args[0]):
+        args = args[0]
     return _ArgFormat(lambda value: _ensure_list(args), ignore_none=False, ignore_missing_value=True)