pacman: add & deprecate options (#30482)

Add:

 * extra_args
 * update_cache_extra_args
 * upgrade_extra_args

which add flexibility.

Deprecate `recurse` which is redundant with extra_args.

`force` is also redundant but is kept for module ergonomics.

lib/ansible/modules/packaging/os/pacman.py

@@ -24,10 +24,11 @@ author:
     - Indrajit Raychaudhuri (@indrajitr)
     - Aaron Bull Schaefer (@elasticdog) <aaron@elasticdog.com>
     - Afterburn
+    - Maxime de Roucy (@tchernomax)
 options:
     name:
         description:
-            - Name or list of names of the packages to install, upgrade, or remove.
+            - Name or list of names of the package(s) or file(s) to install, upgrade, or remove.
         aliases: [ package, pkg ]
 
     state:
@@ -41,33 +42,55 @@ options:
             - When removing a package, also remove its dependencies, provided
               that they are not required by other packages and were not
               explicitly installed by a user.
-        type: bool
+              This option is deprecated since 2.8 and will be removed in 2.10,
+              use `extra_args=--recursive`.
         default: no
+        type: bool
         version_added: "1.3"
 
     force:
         description:
-            - When removing package - force remove package, without any
+            - When removing package, force remove package, without any checks.
-              checks. When update_cache - force redownload repo
+              Same as `extra_args="--nodeps --nodeps"`.
-              databases.
+              When update_cache, force redownload repo databases.
-        type: bool
+              Same as `update_cache_extra_args="--refresh --refresh"`.
         default: no
+        type: bool
         version_added: "2.0"
 
+    extra_args:
+        description:
+            - Additional option to pass to pacman when enforcing C(state).
+        default:
+        version_added: "2.8"
+
     update_cache:
         description:
-            - Whether or not to refresh the master package lists. This can be
+            - Whether or not to refresh the master package lists.
-              run as part of a package installation or as a separate step.
+            - This can be run as part of a package installation or as a separate step.
-        type: bool
         default: no
+        type: bool
         aliases: [ update-cache ]
 
+    update_cache_extra_args:
+        description:
+            - Additional option to pass to pacman when enforcing C(update_cache).
+        default:
+        version_added: "2.8"
+
     upgrade:
         description:
-            - Whether or not to upgrade whole system.
+            - Whether or not to upgrade the whole system.
-        type: bool
         default: no
+        type: bool
         version_added: "2.0"
+
+    upgrade_extra_args:
+        description:
+            - Additional option to pass to pacman when enforcing C(upgrade).
+        default:
+        version_added: "2.8"
+
 notes:
   - When used with a `loop:` each package will be processed individually,
     it is much more efficient to pass the list directly to the `name` option.
@@ -82,11 +105,23 @@ packages:
 '''
 
 EXAMPLES = '''
-- name: Install package foo
+- name: Install package foo from repo
   pacman:
     name: foo
     state: present
 
+- name: Install package bar from file
+  pacman:
+    name: ~/bar-1.0-1-any.pkg.tar.xz
+    state: present
+
+- name: Install package foo from repo and bar from file
+  pacman:
+    name:
+      - foo
+      - ~/bar-1.0-1-any.pkg.tar.xz
+    state: present
+
 - name: Upgrade package foo
   pacman:
     name: foo
@@ -95,14 +130,16 @@ EXAMPLES = '''
 
 - name: Remove packages foo and bar
   pacman:
-    name: foo,bar
+    name:
+      - foo
+      - bar
     state: absent
 
 - name: Recursively remove package baz
   pacman:
     name: baz
     state: absent
-    recurse: yes
+    extra_args: --recursive
 
 - name: Run the equivalent of "pacman -Sy" as a separate step
   pacman:
@@ -143,7 +180,7 @@ def query_package(module, pacman_path, name, state="present"):
     boolean to indicate if the package is up-to-date and a third boolean to indicate whether online information were available
     """
     if state == "present":
-        lcmd = "%s -Qi %s" % (pacman_path, name)
+        lcmd = "%s --query --info %s" % (pacman_path, name)
         lrc, lstdout, lstderr = module.run_command(lcmd, check_rc=False)
         if lrc != 0:
             # package is not installed locally
@@ -152,7 +189,7 @@ def query_package(module, pacman_path, name, state="present"):
         # get the version installed locally (if any)
         lversion = get_version(lstdout)
 
-        rcmd = "%s -Si %s" % (pacman_path, name)
+        rcmd = "%s --sync --info %s" % (pacman_path, name)
         rrc, rstdout, rstderr = module.run_command(rcmd, check_rc=False)
         # get the version in the repository
         rversion = get_version(rstdout)
@@ -167,12 +204,10 @@ def query_package(module, pacman_path, name, state="present"):
 
 
 def update_package_db(module, pacman_path):
-    if module.params["force"]:
+    if module.params['force']:
-        args = "Syy"
+        module.params["update_cache_extra_args"] += " --refresh --refresh"
-    else:
-        args = "Sy"
 
-    cmd = "%s -%s" % (pacman_path, args)
+    cmd = "%s --sync --refresh %s" % (pacman_path, module.params["update_cache_extra_args"])
     rc, stdout, stderr = module.run_command(cmd, check_rc=False)
 
     if rc == 0:
@@ -182,8 +217,8 @@ def update_package_db(module, pacman_path):
 
 
 def upgrade(module, pacman_path):
-    cmdupgrade = "%s -Suq --noconfirm" % (pacman_path)
+    cmdupgrade = "%s --sync --sysupgrade --quiet --noconfirm %s" % (pacman_path, module.params["upgrade_extra_args"])
-    cmdneedrefresh = "%s -Qu" % (pacman_path)
+    cmdneedrefresh = "%s --query --upgrades" % (pacman_path)
     rc, stdout, stderr = module.run_command(cmdneedrefresh, check_rc=False)
     data = stdout.split('\n')
     data.remove('')
@@ -219,15 +254,8 @@ def remove_packages(module, pacman_path, packages):
         'after': '',
     }
 
-    if module.params["recurse"] or module.params["force"]:
+    if module.params["force"]:
-        if module.params["recurse"]:
+        module.params["extra_args"] += " --nodeps --nodeps"
-            args = "Rs"
-        if module.params["force"]:
-            args = "Rdd"
-        if module.params["recurse"] and module.params["force"]:
-            args = "Rdds"
-    else:
-        args = "R"
 
     remove_c = 0
     # Using a for loop in case of error, we can report the package that failed
@@ -237,7 +265,7 @@ def remove_packages(module, pacman_path, packages):
         if not installed:
             continue
 
-        cmd = "%s -%s %s --noconfirm --noprogressbar" % (pacman_path, args, package)
+        cmd = "%s --remove --noconfirm --noprogressbar %s %s" % (pacman_path, module.params["extra_args"], package)
         rc, stdout, stderr = module.run_command(cmd, check_rc=False)
 
         if rc != 0:
@@ -285,7 +313,7 @@ def install_packages(module, pacman_path, state, packages, package_files):
             to_install_repos.append(package)
 
     if to_install_repos:
-        cmd = "%s -S %s --noconfirm --noprogressbar --needed" % (pacman_path, " ".join(to_install_repos))
+        cmd = "%s --sync --noconfirm --noprogressbar --needed %s %s" % (pacman_path, module.params["extra_args"], " ".join(to_install_repos))
         rc, stdout, stderr = module.run_command(cmd, check_rc=False)
 
         if rc != 0:
@@ -301,7 +329,7 @@ def install_packages(module, pacman_path, state, packages, package_files):
         install_c += len(to_install_repos)
 
     if to_install_files:
-        cmd = "%s -U %s --noconfirm --noprogressbar --needed" % (pacman_path, " ".join(to_install_files))
+        cmd = "%s --upgrade --noconfirm --noprogressbar --needed %s %s" % (pacman_path, module.params["extra_args"], " ".join(to_install_files))
         rc, stdout, stderr = module.run_command(cmd, check_rc=False)
 
         if rc != 0:
@@ -362,7 +390,7 @@ def expand_package_groups(module, pacman_path, pkgs):
 
     for pkg in pkgs:
         if pkg:  # avoid empty strings
-            cmd = "%s -Sgq %s" % (pacman_path, pkg)
+            cmd = "%s --sync --groups --quiet %s" % (pacman_path, pkg)
             rc, stdout, stderr = module.run_command(cmd, check_rc=False)
 
             if rc == 0:
@@ -380,12 +408,15 @@ def expand_package_groups(module, pacman_path, pkgs):
 def main():
     module = AnsibleModule(
         argument_spec=dict(
-            name=dict(type='list', aliases=['package', 'pkg']),
+            name=dict(type='list', aliases=['pkg', 'package']),
-            state=dict(type='str', default='present', choices=['absent', 'installed', 'latest', 'present', 'removed']),
+            state=dict(type='str', default='present', choices=['present', 'installed', 'latest', 'absent', 'removed']),
             recurse=dict(type='bool', default=False),
             force=dict(type='bool', default=False),
+            extra_args=dict(type='str', default=''),
             upgrade=dict(type='bool', default=False),
+            upgrade_extra_args=dict(type='str', default=''),
             update_cache=dict(type='bool', default=False, aliases=['update-cache']),
+            update_cache_extra_args=dict(type='str', default=''),
         ),
         required_one_of=[['name', 'update_cache', 'upgrade']],
         supports_check_mode=True,
@@ -401,6 +432,13 @@ def main():
     elif p['state'] in ['absent', 'removed']:
         p['state'] = 'absent'
 
+    if p['recurse']:
+        module.deprecate('Option `recurse` is deprecated and will be removed in '
+                         'version 2.10. Please use `extra_args=--recursive` '
+                         'instead', '2.10')
+        if p['state'] == 'absent':
+            p['extra_args'] += " --recursive"
+
     if p["update_cache"] and not module.check_mode:
         update_package_db(module, pacman_path)
         if not (p['name'] or p['upgrade']):