apt_rpm: add new states 'latest' and 'present_not_latest' (#8247)

* Add new states 'latest' and 'present_not_latest'.

* Improve documentation.

changelogs/fragments/8247-apt_rpm-latest.yml

@@ -0,0 +1,6 @@
+minor_changes:
+  - "apt_rpm - add new states ``latest`` and ``present_not_latest``. The value ``latest`` is equivalent to the current behavior of
+     ``present``, which will upgrade a package if a newer version exists. ``present_not_latest`` does what most users would expect ``present``
+     to do: it does not upgrade if the package is already installed. The current behavior of ``present`` will be deprecated in a later version,
+     and eventually changed to that of ``present_not_latest``
+     (https://github.com/ansible-collections/community.general/issues/8217, https://github.com/ansible-collections/community.general/pull/8247)."

plugins/modules/apt_rpm.py

@@ -37,7 +37,17 @@ options:
   state:
     description:
       - Indicates the desired package state.
-    choices: [ absent, present, installed, removed ]
+      - Please note that V(present) and V(installed) are equivalent to V(latest) right now.
+        This will change in the future. To simply ensure that a package is installed, without upgrading
+        it, use the V(present_not_latest) state.
+      - The states V(latest) and V(present_not_latest) have been added in community.general 8.6.0.
+    choices:
+      - absent
+      - present
+      - present_not_latest
+      - installed
+      - removed
+      - latest
     default: present
     type: str
   update_cache:
@@ -180,7 +190,7 @@ def check_package_version(module, name):
     return False
 
 
-def query_package_provides(module, name):
+def query_package_provides(module, name, allow_upgrade=False):
     # rpm -q returns 0 if the package is installed,
     # 1 if it is not installed
     if name.endswith('.rpm'):
@@ -195,10 +205,11 @@ def query_package_provides(module, name):
 
     rc, out, err = module.run_command("%s -q --provides %s" % (RPM_PATH, name))
     if rc == 0:
+        if not allow_upgrade:
+            return True
         if check_package_version(module, name):
             return True
-    else:
-        return False
+    return False
 
 
 def update_package_db(module):
@@ -255,14 +266,14 @@ def remove_packages(module, packages):
     return (False, "package(s) already absent")
 
 
-def install_packages(module, pkgspec):
+def install_packages(module, pkgspec, allow_upgrade=False):
 
     if pkgspec is None:
         return (False, "Empty package list")
 
     packages = ""
     for package in pkgspec:
-        if not query_package_provides(module, package):
+        if not query_package_provides(module, package, allow_upgrade=allow_upgrade):
             packages += "'%s' " % package
 
     if len(packages) != 0:
@@ -271,7 +282,7 @@ def install_packages(module, pkgspec):
 
         installed = True
         for packages in pkgspec:
-            if not query_package_provides(module, package):
+            if not query_package_provides(module, package, allow_upgrade=False):
                 installed = False
 
         # apt-rpm always have 0 for exit code if --force is used
@@ -286,7 +297,7 @@ def install_packages(module, pkgspec):
 def main():
     module = AnsibleModule(
         argument_spec=dict(
-            state=dict(type='str', default='present', choices=['absent', 'installed', 'present', 'removed']),
+            state=dict(type='str', default='present', choices=['absent', 'installed', 'present', 'removed', 'present_not_latest', 'latest']),
             update_cache=dict(type='bool', default=False),
             clean=dict(type='bool', default=False),
             dist_upgrade=dict(type='bool', default=False),
@@ -320,8 +331,8 @@ def main():
         output += out
 
     packages = p['package']
-    if p['state'] in ['installed', 'present']:
-        (m, out) = install_packages(module, packages)
+    if p['state'] in ['installed', 'present', 'present_not_latest', 'latest']:
+        (m, out) = install_packages(module, packages, allow_upgrade=p['state'] != 'present_not_latest')
         modified = modified or m
         output += out