Add support for state=latest to flatpak module (#8221)

Fixes #6563 by extending the allowed values of the `state` parameter to
include `latest`. To do this, the `update_flat()` function is introduced
which borrows the majority of its implementation from both the existing
`install_flat()` and `remove_flat()` functions. The documentation and
examples have been expanded describing what to expect when using
`state=latest`.

plugins/modules/flatpak.py

@@ -26,7 +26,9 @@ extends_documentation_fragment:
   - community.general.attributes
 attributes:
   check_mode:
-    support: full
+    support: partial
+    details:
+      - If O(state=latest), the module will always return C(changed=true).
   diff_mode:
     support: none
 options:
@@ -53,12 +55,12 @@ options:
     - Both C(https://) and C(http://) URLs are supported.
     - When supplying a reverse DNS name, you can use the O(remote) option to specify on what remote
       to look for the flatpak. An example for a reverse DNS name is C(org.gnome.gedit).
-    - When used with O(state=absent), it is recommended to specify the name in the reverse DNS
-      format.
-    - When supplying a URL with O(state=absent), the module will try to match the
-      installed flatpak based on the name of the flatpakref to remove it. However, there is no
-      guarantee that the names of the flatpakref file and the reverse DNS name of the installed
-      flatpak do match.
+    - When used with O(state=absent) or O(state=latest), it is recommended to specify the name in
+      the reverse DNS format.
+    - When supplying a URL with O(state=absent) or O(state=latest), the module will try to match the
+      installed flatpak based on the name of the flatpakref to remove or update it. However, there
+      is no guarantee that the names of the flatpakref file and the reverse DNS name of the
+      installed flatpak do match.
     type: list
     elements: str
     required: true
@@ -82,7 +84,8 @@ options:
   state:
     description:
     - Indicates the desired package state.
-    choices: [ absent, present ]
+    - The value V(latest) is supported since community.general 8.6.0.
+    choices: [ absent, present, latest ]
     type: str
     default: present
 '''
@@ -118,6 +121,37 @@ EXAMPLES = r'''
       - org.inkscape.Inkscape
       - org.mozilla.firefox
 
+- name: Update the spotify flatpak
+  community.general.flatpak:
+    name:  https://s3.amazonaws.com/alexlarsson/spotify-repo/spotify.flatpakref
+    state: latest
+
+- name: Update the gedit flatpak package without dependencies (not recommended)
+  community.general.flatpak:
+    name: https://git.gnome.org/browse/gnome-apps-nightly/plain/gedit.flatpakref
+    state: latest
+    no_dependencies: true
+
+- name: Update the gedit package from flathub for current user
+  community.general.flatpak:
+    name: org.gnome.gedit
+    state: latest
+    method: user
+
+- name: Update the Gnome Calendar flatpak from the gnome remote system-wide
+  community.general.flatpak:
+    name: org.gnome.Calendar
+    state: latest
+    remote: gnome
+
+- name: Update multiple packages
+  community.general.flatpak:
+    name:
+      - org.gimp.GIMP
+      - org.inkscape.Inkscape
+      - org.mozilla.firefox
+    state: latest
+
 - name: Remove the gedit flatpak
   community.general.flatpak:
     name: org.gnome.gedit
@@ -195,6 +229,28 @@ def install_flat(module, binary, remote, names, method, no_dependencies):
     result['changed'] = True
 
 
+def update_flat(module, binary, names, method, no_dependencies):
+    """Update existing flatpaks."""
+    global result  # pylint: disable=global-variable-not-assigned
+    installed_flat_names = [
+        _match_installed_flat_name(module, binary, name, method)
+        for name in names
+    ]
+    command = [binary, "update", "--{0}".format(method)]
+    flatpak_version = _flatpak_version(module, binary)
+    if LooseVersion(flatpak_version) < LooseVersion('1.1.3'):
+        command += ["-y"]
+    else:
+        command += ["--noninteractive"]
+    if no_dependencies:
+        command += ["--no-deps"]
+    command += installed_flat_names
+    stdout = _flatpak_command(module, module.check_mode, command)
+    result["changed"] = (
+        True if module.check_mode else stdout.find("Nothing to do.") == -1
+    )
+
+
 def uninstall_flat(module, binary, names, method):
     """Remove existing flatpaks."""
     global result  # pylint: disable=global-variable-not-assigned
@@ -313,7 +369,7 @@ def main():
             method=dict(type='str', default='system',
                         choices=['user', 'system']),
             state=dict(type='str', default='present',
-                       choices=['absent', 'present']),
+                       choices=['absent', 'present', 'latest']),
             no_dependencies=dict(type='bool', default=False),
             executable=dict(type='path', default='flatpak')
         ),
@@ -338,10 +394,13 @@ def main():
         module.fail_json(msg="Executable '%s' was not found on the system." % executable, **result)
 
     installed, not_installed = flatpak_exists(module, binary, name, method)
-    if state == 'present' and not_installed:
-        install_flat(module, binary, remote, not_installed, method, no_dependencies)
-    elif state == 'absent' and installed:
+    if state == 'absent' and installed:
         uninstall_flat(module, binary, installed, method)
+    else:
+        if state == 'latest' and installed:
+            update_flat(module, binary, installed, method, no_dependencies)
+        if state in ('present', 'latest') and not_installed:
+            install_flat(module, binary, remote, not_installed, method, no_dependencies)
 
     module.exit_json(**result)