apt_rpm: add clean and upgrade

* clean performs apt-get clean.

* upgrade performs apt-get dist-upgrade.

* update_cache, clean and upgrade can be used with and without specified packages.

plugins/modules/apt_rpm.py

@@ -20,8 +20,7 @@
 options:
   package:
     description:
-      - list of packages to install, upgrade or remove.
-    required: true
+      - List of packages to install, upgrade or remove.
     aliases: [ name, pkg ]
     type: list
     elements: str
@@ -33,7 +32,20 @@
     type: str
   update_cache:
     description:
-      - update the package database first C(apt-get update).
+      - Run the equivalent of C(apt-get update) before the operation. Can be run as part of the package installation or as a separate step.
+      - Default is not to update the cache.
+    type: bool
+    default: false
+  clean:
+    description:
+      - Run the equivalent of C(apt-get clean) to clear out the local repository of retrieved package files. It removes everything but
+        the lock file from /var/cache/apt/archives/ and /var/cache/apt/archives/partial/.
+      - Can be run as part of the package installation (clean runs before install) or as a separate step.
+    type: bool
+    default: false
+  upgrade:
+    description:
+      - If true performs an apt-get dist-upgrade.
     type: bool
     default: false
 author:
@@ -69,6 +81,15 @@
     name: bar
     state: present
     update_cache: true
+
+- name: Run the equivalent of "apt-get clean" as a separate step
+  community.general.apt_rpm:
+    clean: yes
+
+- name: Perform cache update and complete system upgrade
+  community.general.apt_rpm:
+    update_cache: true
+    upgrade: true
 '''
 
 import os
@@ -102,6 +123,26 @@ def update_package_db(module):
     if rc != 0:
         module.fail_json(msg="could not update package db: %s" % err)
 
+    return out
+
+
+def clean(module):
+    rc, out, err = module.run_command("%s clean" % APT_PATH)
+
+    if rc != 0:
+        module.fail_json(msg="apt-get clean failed: %s" % err)
+
+    return "Cleaned\n"
+
+
+def upgrade(module):
+    rc, out, err = module.run_command("%s -y dist-upgrade" % APT_PATH)
+
+    if rc != 0:
+        module.fail_json(msg="apt-get dist-upgrade failed: %s" % err)
+
+    return out
+
 
 def remove_packages(module, packages):
 
@@ -155,7 +196,9 @@ def main():
         argument_spec=dict(
             state=dict(type='str', default='present', choices=['absent', 'installed', 'present', 'removed']),
             update_cache=dict(type='bool', default=False),
-            package=dict(type='list', elements='str', required=True, aliases=['name', 'pkg']),
+            clean=dict(type='bool', default=False),
+            upgrade=dict(type='bool', default=False),
+            package=dict(type='list', elements='str', aliases=['name', 'pkg']),
         ),
     )
 
@@ -164,16 +207,32 @@ def main():
 
     p = module.params
 
+    out = ""
     if p['update_cache']:
-        update_package_db(module)
+        out += update_package_db(module)
+
+    if p['clean']:
+        out += clean(module)
 
+    if p['upgrade']:
+        out += upgrade(module)
+
+    # If package is missing return exit_json
     packages = p['package']
 
-    if p['state'] in ['installed', 'present']:
-        install_packages(module, packages)
+    if not isinstance(packages, list):
+        if out == '':
+            module.fail_json(msg="Missing command")
+
+        else:
+            module.exit_json(changed=True, msg=out)
+
+    else:
+        if p['state'] in ['installed', 'present']:
+            install_packages(module, packages)
 
-    elif p['state'] in ['absent', 'removed']:
-        remove_packages(module, packages)
+        elif p['state'] in ['absent', 'removed']:
+            remove_packages(module, packages)
 
 
 if __name__ == '__main__':