From 9286b601820e497804537713744eb901b24de7e3 Mon Sep 17 00:00:00 2001
From: Alexei Znamensky <103110+russoz@users.noreply.github.com>
Date: Sat, 22 Mar 2025 09:04:59 +1300
Subject: [PATCH] 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()
---
 .../9893-cmdrunner-as-fixed-args.yml          |  2 +
 docs/docsite/rst/guide_cmdrunner.rst          | 56 ++++++++++++++-----
 plugins/module_utils/cmd_runner_fmt.py        |  4 +-
 3 files changed, 48 insertions(+), 14 deletions(-)
 create mode 100644 changelogs/fragments/9893-cmdrunner-as-fixed-args.yml

diff --git a/changelogs/fragments/9893-cmdrunner-as-fixed-args.yml b/changelogs/fragments/9893-cmdrunner-as-fixed-args.yml
new file mode 100644
index 0000000000..109b552385
--- /dev/null
+++ b/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).
diff --git a/docs/docsite/rst/guide_cmdrunner.rst b/docs/docsite/rst/guide_cmdrunner.rst
index f7b70a86e1..c1514ee340 100644
--- a/docs/docsite/rst/guide_cmdrunner.rst
+++ b/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
-    is provided then it is ignored.
-    The function returns ``arg`` as-is.
+    This method defines one or more fixed arguments that are returned by the generated function
+    regardless whether ``value`` is passed to it or not.
 
-    - Creation:
-        ``cmd_runner_fmt.as_fixed("--version")``
+    This method accepts these arguments in one of three forms:
+
+        * 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               |
-        +=========+=======================+
-        |         | ``["--version"]``     |
-        +---------+-----------------------+
-        | 57      | ``["--version"]``     |
-        +---------+-----------------------+
+        +---------+--------------------------------------+
+        | Value   | Outcome                              |
+        +=========+======================================+
+        |         | * ``["--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.
 
diff --git a/plugins/module_utils/cmd_runner_fmt.py b/plugins/module_utils/cmd_runner_fmt.py
index bd6d00a15d..8b415edcf9 100644
--- a/plugins/module_utils/cmd_runner_fmt.py
+++ b/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)