From 76b6c8e18493e03c19d171f1bda5f03a91d374e9 Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Wed, 2 Oct 2024 21:29:40 +0300 Subject: [PATCH] [PR #8963/96dfb89b backport][stable-9] cmd_runner_guide: docs improvements (#8968) cmd_runner_guide: docs improvements (#8963) * cmd_runner_guide: docs improvements * add note about suboptions (cherry picked from commit 96dfb89b0171b9b3c9af009a462327b329aa1ee6) Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com> --- docs/docsite/rst/guide_cmdrunner.rst | 60 +++++++++++++++++++--------- 1 file changed, 42 insertions(+), 18 deletions(-) diff --git a/docs/docsite/rst/guide_cmdrunner.rst b/docs/docsite/rst/guide_cmdrunner.rst index d4f12cf81e..d491769c18 100644 --- a/docs/docsite/rst/guide_cmdrunner.rst +++ b/docs/docsite/rst/guide_cmdrunner.rst @@ -68,20 +68,27 @@ This is meant to be done once, then every time you need to execute the command y with runner("version") as ctx: dummy, stdout, dummy = ctx.run() + # passes arg 'data' to AnsibleModule.run_command() + with runner("type name", data=stdin_data) as ctx: + dummy, stdout, dummy = ctx.run() + # Another way of expressing it dummy, stdout, dummy = runner("version").run() -Note that you can pass values for the arguments when calling ``run()``, -otherwise ``CmdRunner`` uses the module options with the exact same names to -provide values for the runner arguments. If no value is passed and no module option -is found for the name specified, then an exception is raised, unless the -argument is using ``cmd_runner_fmt.as_fixed`` as format function like the -``version`` in the example above. See more about it below. +Note that you can pass values for the arguments when calling ``run()``, otherwise ``CmdRunner`` +uses the module options with the exact same names to provide values for the runner arguments. +If no value is passed and no module option is found for the name specified, then an exception is raised, unless +the argument is using ``cmd_runner_fmt.as_fixed`` as format function like the ``version`` in the example above. +See more about it below. In the first example, values of ``type``, ``force``, ``no_deps`` and others are taken straight from the module, whilst ``galaxy_cmd`` and ``upgrade`` are passed explicitly. +.. note:: + + It is not possible to automatically retrieve values of suboptions. + That generates a resulting command line similar to (example taken from the output of an integration test): @@ -110,7 +117,7 @@ into something formatted for the command line. Argument format function """""""""""""""""""""""" -An ``arg_format`` function should be of the form: +An ``arg_format`` function is defined in the form similar to: .. code-block:: python @@ -155,7 +162,7 @@ In these descriptions ``value`` refers to the single parameter passed to the for - Creation: ``cmd_runner_fmt.as_list()`` - - Example: + - Examples: +----------------------+---------------------+ | Value | Outcome | +======================+=====================+ @@ -167,12 +174,11 @@ In these descriptions ``value`` refers to the single parameter passed to the for - ``cmd_runner_fmt.as_bool()`` This method receives two different parameters: ``args_true`` and ``args_false``, latter being optional. If the boolean evaluation of ``value`` is ``True``, the format function returns ``args_true``. - If the boolean evaluation is ``False``, then the function returns ``args_false`` - if it was provided, or ``[]`` otherwise. + If the boolean evaluation is ``False``, then the function returns ``args_false`` if it was provided, or ``[]`` otherwise. - - Creation: + - Creation (one arg): ``cmd_runner_fmt.as_bool("--force")`` - - Example: + - Examples: +------------+--------------------+ | Value | Outcome | +============+====================+ @@ -180,6 +186,18 @@ In these descriptions ``value`` refers to the single parameter passed to the for +------------+--------------------+ | ``False`` | ``[]`` | +------------+--------------------+ + - Creation (two args): + ``cmd_runner_fmt.as_bool("--relax", "--dont-do-it")`` + - Examples: + +------------+----------------------+ + | Value | Outcome | + +============+======================+ + | ``True`` | ``["--relax"]`` | + +------------+----------------------+ + | ``False`` | ``["--dont-do-it"]`` | + +------------+----------------------+ + | | ``[]`` | + +------------+----------------------+ - ``cmd_runner_fmt.as_bool_not()`` This method receives one parameter, which is returned by the function when the boolean evaluation @@ -187,7 +205,7 @@ In these descriptions ``value`` refers to the single parameter passed to the for - Creation: ``cmd_runner_fmt.as_bool_not("--no-deps")`` - - Example: + - Examples: +-------------+---------------------+ | Value | Outcome | +=============+=====================+ @@ -202,7 +220,7 @@ In these descriptions ``value`` refers to the single parameter passed to the for - Creation: ``cmd_runner_fmt.as_optval("-i")`` - - Example: + - Examples: +---------------+---------------------+ | Value | Outcome | +===============+=====================+ @@ -216,7 +234,7 @@ In these descriptions ``value`` refers to the single parameter passed to the for - Creation: ``cmd_runner_fmt.as_opt_val("--name")`` - - Example: + - Examples: +--------------+--------------------------+ | Value | Outcome | +==============+==========================+ @@ -229,7 +247,7 @@ In these descriptions ``value`` refers to the single parameter passed to the for - Creation: ``cmd_runner_fmt.as_opt_eq_val("--num-cpus")`` - - Example: + - Examples: +------------+-------------------------+ | Value | Outcome | +============+=========================+ @@ -243,7 +261,7 @@ In these descriptions ``value`` refers to the single parameter passed to the for - Creation: ``cmd_runner_fmt.as_fixed("--version")`` - - Example: + - Examples: +---------+-----------------------+ | Value | Outcome | +=========+=======================+ @@ -265,7 +283,7 @@ In these descriptions ``value`` refers to the single parameter passed to the for - Creation: ``cmd_runner_fmt.as_map(dict(a=1, b=2, c=3), default=42)`` - - Example: + - Examples: +---------------------+---------------+ | Value | Outcome | +=====================+===============+ @@ -359,6 +377,8 @@ Settings that can be passed to the ``CmdRunner`` constructor are: Command to be executed. It can be a single string, the executable name, or a list of strings containing the executable name as the first element and, optionally, fixed parameters. Those parameters are used in all executions of the runner. + The *executable* pointed by this parameter (whether itself when ``str`` or its first element when ``list``) is + processed using ``AnsibleModule.get_bin_path()`` *unless* it is an absolute path or contains the character ``/``. - ``arg_formats: dict`` Mapping of argument names to formatting functions. - ``default_args_order: str`` @@ -394,6 +414,10 @@ When creating a context, the additional settings that can be passed to the call Defaults to ``False``. - ``check_mode_return: any`` If ``check_mode_skip=True``, then return this value instead. +- valid named arguments to ``AnsibleModule.run_command()`` + Other than ``args``, any valid argument to ``run_command()`` can be passed when setting up the run context. + For example, ``data`` can be used to send information to the command's standard input. + Or ``cwd`` can be used to run the command inside a specific working directory. Additionally, any other valid parameters for ``AnsibleModule.run_command()`` may be passed, but unexpected behavior might occur if redefining options already present in the runner or its context creation. Use with caution.