pipx: add state latest (#5105)

* pipx: add state latest

* add changelog fragment

* Update plugins/modules/packaging/language/pipx.py

Co-authored-by: Felix Fontein <felix@fontein.de>

Co-authored-by: Felix Fontein <felix@fontein.de>

changelogs/fragments/5105-pipx-state-latest.yaml

@@ -0,0 +1,2 @@
+minor_changes:
+  - pipx - added state ``latest`` to the module (https://github.com/ansible-collections/community.general/pull/5105).

plugins/modules/packaging/language/pipx.py

@@ -19,11 +19,13 @@ description:
 options:
     state:
         type: str
-        choices: [present, absent, install, uninstall, uninstall_all, inject, upgrade, upgrade_all, reinstall, reinstall_all]
+        choices: [present, absent, install, uninstall, uninstall_all, inject, upgrade, upgrade_all, reinstall, reinstall_all, latest]
         default: install
         description:
             - Desired state for the application.
             - The states C(present) and C(absent) are aliases to C(install) and C(uninstall), respectively.
+            - The state C(latest) is equivalent to executing the task twice, with state C(install) and then C(upgrade).
+              It was added in community.general 5.5.0.
     name:
         type: str
         description:
@@ -146,7 +148,7 @@ class PipX(StateModuleHelper):
         argument_spec=dict(
             state=dict(type='str', default='install',
                        choices=['present', 'absent', 'install', 'uninstall', 'uninstall_all',
-                                'inject', 'upgrade', 'upgrade_all', 'reinstall', 'reinstall_all']),
+                                'inject', 'upgrade', 'upgrade_all', 'reinstall', 'reinstall_all', 'latest']),
             name=dict(type='str'),
             source=dict(type='str'),
             install_deps=dict(type='bool', default=False),
@@ -166,6 +168,7 @@ class PipX(StateModuleHelper):
             ('state', 'uninstall', ['name']),
             ('state', 'upgrade', ['name']),
             ('state', 'reinstall', ['name']),
+            ('state', 'latest', ['name']),
             ('state', 'inject', ['name', 'inject_packages']),
         ],
         supports_check_mode=True,
@@ -279,6 +282,17 @@ class PipX(StateModuleHelper):
             ctx.run()
             self._capture_results(ctx)
 
+    def state_latest(self):
+        if not self.vars.application or self.vars.force:
+            self.changed = True
+            with self.runner('state index_url install_deps force python editable pip_args name_source', check_mode_skip=True) as ctx:
+                ctx.run(state='install', name_source=[self.vars.name, self.vars.source])
+                self._capture_results(ctx)
+
+        with self.runner('state index_url install_deps force editable pip_args name', check_mode_skip=True) as ctx:
+            ctx.run(state='upgrade')
+            self._capture_results(ctx)
+
 
 def main():
     PipX.execute()

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

@@ -20,6 +20,10 @@
     name: tox
   register: install_tox
 
+- name: set fact latest_tox_version
+  set_fact:
+    latest_tox_version: "{{ install_tox.application.tox.version }}"
+
 - name: install application tox again
   community.general.pipx:
     name: tox
@@ -66,7 +70,7 @@
   register: reinstall_noname
   ignore_errors: yes
 
-- name: upgrade tox 3.24.0
+- name: upgrade tox from 3.24.0
   community.general.pipx:
     name: tox
     state: upgrade
@@ -108,6 +112,65 @@
       - upgrade_noname is failed
       - reinstall_noname is failed
 
+##############################################################################
+- name: install application latest tox
+  community.general.pipx:
+    name: tox
+    state: latest
+  register: install_tox_latest
+
+- name: cleanup tox latest
+  community.general.pipx:
+    state: absent
+    name: tox
+  register: uninstall_tox_latest
+
+- name: install application tox 3.24.0 for latest
+  community.general.pipx:
+    name: tox
+    source: tox==3.24.0
+  register: install_tox_324_for_latest
+
+- name: install application latest tox
+  community.general.pipx:
+    name: tox
+    state: latest
+  register: install_tox_latest_with_preinstall
+
+- name: install application latest tox again
+  community.general.pipx:
+    name: tox
+    state: latest
+  register: install_tox_latest_with_preinstall_again
+
+- name: install application latest tox
+  community.general.pipx:
+    name: tox
+    state: latest
+    force: true
+  register: install_tox_latest_with_preinstall_again_force
+
+- name: cleanup tox latest again
+  community.general.pipx:
+    state: absent
+    name: tox
+  register: uninstall_tox_latest_again
+
+- name: check assertions tox latest
+  assert:
+    that:
+      - install_tox_latest is changed
+      - uninstall_tox_latest is changed
+      - install_tox_324_for_latest is changed
+      - install_tox_324_for_latest.application.tox.version == '3.24.0'
+      - install_tox_latest_with_preinstall is changed
+      - install_tox_latest_with_preinstall.application.tox.version == latest_tox_version
+      - install_tox_latest_with_preinstall_again is not changed
+      - install_tox_latest_with_preinstall_again.application.tox.version == latest_tox_version
+      - install_tox_latest_with_preinstall_again_force is changed
+      - install_tox_latest_with_preinstall_again_force.application.tox.version == latest_tox_version
+      - uninstall_tox_latest_again is changed
+
 ##############################################################################
 - name: ensure application ansible-lint is uninstalled
   community.general.pipx:
@@ -144,6 +207,7 @@
 
 ##############################################################################
 - name: install jupyter - not working smoothly in freebsd
+  when: ansible_system != 'FreeBSD'
   block:
     - name: ensure application jupyter is uninstalled
       community.general.pipx:
@@ -166,4 +230,3 @@
         that:
           - install_jupyter is changed
           - '"ipython" in install_jupyter.stdout'
-  when: ansible_system != 'FreeBSD'