pipx/pipx_info: add return value version (#9180)

* pipx/pipx_info: add return value version

* add changelog frag

changelogs/fragments/9180-pipx-version.yml

@@ -0,0 +1,3 @@
+minor_changes:
+  - pipx - add return value ``version`` (https://github.com/ansible-collections/community.general/pull/9180).
+  - pipx_info - add return value ``version`` (https://github.com/ansible-collections/community.general/pull/9180).

plugins/module_utils/pipx.py

@@ -10,7 +10,7 @@ __metaclass__ = type
 import json
 
 
-from ansible_collections.community.general.plugins.module_utils.cmd_runner import CmdRunner, cmd_runner_fmt as fmt
+from ansible_collections.community.general.plugins.module_utils.cmd_runner import CmdRunner, cmd_runner_fmt
 
 
 pipx_common_argspec = {
@@ -40,24 +40,25 @@ _state_map = dict(
 
 def pipx_runner(module, command, **kwargs):
     arg_formats = dict(
-        state=fmt.as_map(_state_map),
+        state=cmd_runner_fmt.as_map(_state_map),
-        name=fmt.as_list(),
+        name=cmd_runner_fmt.as_list(),
-        name_source=fmt.as_func(fmt.unpack_args(lambda n, s: [s] if s else [n])),
+        name_source=cmd_runner_fmt.as_func(cmd_runner_fmt.unpack_args(lambda n, s: [s] if s else [n])),
-        install_apps=fmt.as_bool("--include-apps"),
+        install_apps=cmd_runner_fmt.as_bool("--include-apps"),
-        install_deps=fmt.as_bool("--include-deps"),
+        install_deps=cmd_runner_fmt.as_bool("--include-deps"),
-        inject_packages=fmt.as_list(),
+        inject_packages=cmd_runner_fmt.as_list(),
-        force=fmt.as_bool("--force"),
+        force=cmd_runner_fmt.as_bool("--force"),
-        include_injected=fmt.as_bool("--include-injected"),
+        include_injected=cmd_runner_fmt.as_bool("--include-injected"),
-        index_url=fmt.as_opt_val('--index-url'),
+        index_url=cmd_runner_fmt.as_opt_val('--index-url'),
-        python=fmt.as_opt_val('--python'),
+        python=cmd_runner_fmt.as_opt_val('--python'),
-        system_site_packages=fmt.as_bool("--system-site-packages"),
+        system_site_packages=cmd_runner_fmt.as_bool("--system-site-packages"),
-        _list=fmt.as_fixed(['list', '--include-injected', '--json']),
+        _list=cmd_runner_fmt.as_fixed(['list', '--include-injected', '--json']),
-        editable=fmt.as_bool("--editable"),
+        editable=cmd_runner_fmt.as_bool("--editable"),
-        pip_args=fmt.as_opt_eq_val('--pip-args'),
+        pip_args=cmd_runner_fmt.as_opt_eq_val('--pip-args'),
-        suffix=fmt.as_opt_val('--suffix'),
+        suffix=cmd_runner_fmt.as_opt_val('--suffix'),
-        spec_metadata=fmt.as_list(),
+        spec_metadata=cmd_runner_fmt.as_list(),
+        version=cmd_runner_fmt.as_fixed('--version'),
     )
-    arg_formats["global"] = fmt.as_bool("--global")
+    arg_formats["global"] = cmd_runner_fmt.as_bool("--global")
 
     runner = CmdRunner(
         module,

plugins/modules/pipx.py

@@ -190,6 +190,15 @@ EXAMPLES = """
   with_items: "{{ pipx_packages }}"
 """
 
+RETURN = """
+version:
+  description: Version of pipx.
+  type: str
+  returned: always
+  sample: "1.7.1"
+  version_added: 10.1.0
+"""
+
 
 from ansible_collections.community.general.plugins.module_utils.module_helper import StateModuleHelper
 from ansible_collections.community.general.plugins.module_utils.pipx import pipx_runner, pipx_common_argspec, make_process_list
@@ -272,6 +281,10 @@ class PipX(StateModuleHelper):
 
         self.vars.set('application', self._retrieve_installed(), change=True, diff=True)
 
+        with self.runner("version") as ctx:
+            rc, out, err = ctx.run()
+            self.vars.version = out.strip()
+
     def __quit_module__(self):
         self.vars.application = self._retrieve_installed()
 

plugins/modules/pipx_info.py

@@ -119,6 +119,13 @@ cmd:
   type: list
   elements: str
   sample: ["/usr/bin/python3.10", "-m", "pipx", "list", "--include-injected", "--json"]
+
+version:
+  description: Version of pipx.
+  type: str
+  returned: always
+  sample: "1.7.1"
+  version_added: 10.1.0
 """
 
 from ansible_collections.community.general.plugins.module_utils.module_helper import ModuleHelper
@@ -149,6 +156,9 @@ class PipXInfo(ModuleHelper):
             facts = ansible_facts(self.module, gather_subset=['python'])
             self.command = [facts['python']['executable'], '-m', 'pipx']
         self.runner = pipx_runner(self.module, self.command)
+        with self.runner("version") as ctx:
+            rc, out, err = ctx.run()
+            self.vars.version = out.strip()
 
     def __run__(self):
         output_process = make_process_list(self, **self.vars.as_dict())

tests/integration/targets/pipx/tasks/main.yml

@@ -57,6 +57,7 @@
   assert:
     that:
       - install_tox is changed
+      - "'version' in install_tox"
       - "'tox' in install_tox.application"
       - install_tox_again is not changed
       - install_tox_again_force is changed