Various updates to macports module (#44605)

- Add support for installing specific variants of a port.
- Add support for using yaml lists with 'name' parameter, rather than comma-separated lists.
- Add to and clarify documentation and examples.
- Use Macports nomenclature:
  - s/package/port/g
  - Rename update_cache to sync_ports but keep update_cache as an alias. Remove undocumented update-cache alias.
  - Remove undocumented 'pkg' alias for 'name'. Replace with 'port' alias and document it.
- Print stdout and stderr output if `port sync` fails.
- Print stderr output, rather than stdout, if `port install/uninstall/activate/deactivate` fail.

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

@@ -22,43 +22,67 @@ module: macports
 author: "Jimmy Tang (@jcftang)"
 short_description: Package manager for MacPorts
 description:
-    - Manages MacPorts packages
+    - Manages MacPorts packages (ports)
 version_added: "1.1"
 options:
     name:
         description:
-            - name of package to install/remove
+            - A list of port names.
+        aliases: ['port']
         required: true
     state:
         description:
-            - state of the package
+            - Indicates the desired state of the port.
         choices: [ 'present', 'absent', 'active', 'inactive' ]
         default: present
-    update_cache:
+    update_ports:
         description:
-            - update the package db first
+            - Update the ports tree first.
+        aliases: ['update_cache']
         default: "no"
         type: bool
+    variant:
+        description:
+            - A port variant specification.
+            - 'C(variant) is only supported with state: I(installed)/I(present).'
+        aliases: ['variants']
+        version_added: "2.7"
 '''
 EXAMPLES = '''
-- macports:
+- name: Install the foo port
+  macports:
     name: foo
-    state: present
 
-- macports:
+- name: Install the universal, x11 variant of the foo port
+  macports:
     name: foo
-    state: present
+    variant: +universal+x11
-    update_cache: yes
 
-- macports:
+- name: Install a list of ports
+  macports:
+    name: "{{ ports }}"
+  vars:
+    ports:
+    - foo
+    - foo-tools
+
+- name: Update the ports tree then install the foo port
+  macports:
+    name: foo
+    update_ports: yes
+
+- name: Remove the foo port
+  macports:
     name: foo
     state: absent
 
-- macports:
+- name: Activate the foo port
+  macports:
     name: foo
     state: active
 
-- macports:
+- name: Deactivate the foo port
+  macports:
     name: foo
     state: inactive
 '''
@@ -67,17 +91,17 @@ from ansible.module_utils.basic import AnsibleModule
 from ansible.module_utils.six.moves import shlex_quote
 
 
-def update_package_db(module, port_path):
+def sync_ports(module, port_path):
-    """ Updates packages list. """
+    """ Sync ports tree. """
 
     rc, out, err = module.run_command("%s sync" % port_path)
 
     if rc != 0:
-        module.fail_json(msg="could not update package db")
+        module.fail_json(msg="Could not update ports tree", stdout=out, stderr=err)
 
 
-def query_package(module, port_path, name, state="present"):
+def query_port(module, port_path, name, state="present"):
-    """ Returns whether a package is installed or not. """
+    """ Returns whether a port is installed or not. """
 
     if state == "present":
 
@@ -97,108 +121,109 @@ def query_package(module, port_path, name, state="present"):
         return False
 
 
-def remove_packages(module, port_path, packages):
+def remove_ports(module, port_path, ports):
-    """ Uninstalls one or more packages if installed. """
+    """ Uninstalls one or more ports if installed. """
 
     remove_c = 0
-    # Using a for loop in case of error, we can report the package that failed
+    # Using a for loop in case of error, we can report the port that failed
-    for package in packages:
+    for port in ports:
-        # Query the package first, to see if we even need to remove
+        # Query the port first, to see if we even need to remove
-        if not query_package(module, port_path, package):
+        if not query_port(module, port_path, port):
             continue
 
-        rc, out, err = module.run_command("%s uninstall %s" % (port_path, package))
+        rc, out, err = module.run_command("%s uninstall %s" % (port_path, port))
 
-        if query_package(module, port_path, package):
+        if query_port(module, port_path, port):
-            module.fail_json(msg="failed to remove %s: %s" % (package, out))
+            module.fail_json(msg="Failed to remove %s: %s" % (port, err))
 
         remove_c += 1
 
     if remove_c > 0:
 
-        module.exit_json(changed=True, msg="removed %s package(s)" % remove_c)
+        module.exit_json(changed=True, msg="Removed %s port(s)" % remove_c)
 
-    module.exit_json(changed=False, msg="package(s) already absent")
+    module.exit_json(changed=False, msg="Port(s) already absent")
 
 
-def install_packages(module, port_path, packages):
+def install_ports(module, port_path, ports, variant):
-    """ Installs one or more packages if not already installed. """
+    """ Installs one or more ports if not already installed. """
 
     install_c = 0
 
-    for package in packages:
+    for port in ports:
-        if query_package(module, port_path, package):
+        if query_port(module, port_path, port):
             continue
 
-        rc, out, err = module.run_command("%s install %s" % (port_path, package))
+        rc, out, err = module.run_command("%s install %s %s" % (port_path, port, variant))
 
-        if not query_package(module, port_path, package):
+        if not query_port(module, port_path, port):
-            module.fail_json(msg="failed to install %s: %s" % (package, out))
+            module.fail_json(msg="Failed to install %s: %s" % (port, err))
 
         install_c += 1
 
     if install_c > 0:
-        module.exit_json(changed=True, msg="installed %s package(s)" % (install_c))
+        module.exit_json(changed=True, msg="Installed %s port(s)" % (install_c))
 
-    module.exit_json(changed=False, msg="package(s) already present")
+    module.exit_json(changed=False, msg="Port(s) already present")
 
 
-def activate_packages(module, port_path, packages):
+def activate_ports(module, port_path, ports):
-    """ Activate a package if it's inactive. """
+    """ Activate a port if it's inactive. """
 
     activate_c = 0
 
-    for package in packages:
+    for port in ports:
-        if not query_package(module, port_path, package):
+        if not query_port(module, port_path, port):
-            module.fail_json(msg="failed to activate %s, package(s) not present" % (package))
+            module.fail_json(msg="Failed to activate %s, port(s) not present" % (port))
 
-        if query_package(module, port_path, package, state="active"):
+        if query_port(module, port_path, port, state="active"):
             continue
 
-        rc, out, err = module.run_command("%s activate %s" % (port_path, package))
+        rc, out, err = module.run_command("%s activate %s" % (port_path, port))
 
-        if not query_package(module, port_path, package, state="active"):
+        if not query_port(module, port_path, port, state="active"):
-            module.fail_json(msg="failed to activate %s: %s" % (package, out))
+            module.fail_json(msg="Failed to activate %s: %s" % (port, err))
 
         activate_c += 1
 
     if activate_c > 0:
-        module.exit_json(changed=True, msg="activated %s package(s)" % (activate_c))
+        module.exit_json(changed=True, msg="Activated %s port(s)" % (activate_c))
 
-    module.exit_json(changed=False, msg="package(s) already active")
+    module.exit_json(changed=False, msg="Port(s) already active")
 
 
-def deactivate_packages(module, port_path, packages):
+def deactivate_ports(module, port_path, ports):
-    """ Deactivate a package if it's active. """
+    """ Deactivate a port if it's active. """
 
     deactivated_c = 0
 
-    for package in packages:
+    for port in ports:
-        if not query_package(module, port_path, package):
+        if not query_port(module, port_path, port):
-            module.fail_json(msg="failed to activate %s, package(s) not present" % (package))
+            module.fail_json(msg="Failed to deactivate %s, port(s) not present" % (port))
 
-        if not query_package(module, port_path, package, state="active"):
+        if not query_port(module, port_path, port, state="active"):
             continue
 
-        rc, out, err = module.run_command("%s deactivate %s" % (port_path, package))
+        rc, out, err = module.run_command("%s deactivate %s" % (port_path, port))
 
-        if query_package(module, port_path, package, state="active"):
+        if query_port(module, port_path, port, state="active"):
-            module.fail_json(msg="failed to deactivated %s: %s" % (package, out))
+            module.fail_json(msg="Failed to deactivate %s: %s" % (port, err))
 
         deactivated_c += 1
 
     if deactivated_c > 0:
-        module.exit_json(changed=True, msg="deactivated %s package(s)" % (deactivated_c))
+        module.exit_json(changed=True, msg="Deactivated %s port(s)" % (deactivated_c))
 
-    module.exit_json(changed=False, msg="package(s) already inactive")
+    module.exit_json(changed=False, msg="Port(s) already inactive")
 
 
 def main():
     module = AnsibleModule(
         argument_spec=dict(
-            name=dict(aliases=["pkg"], required=True),
+            name=dict(aliases=["port"], required=True, type='list'),
             state=dict(default="present", choices=["present", "installed", "absent", "removed", "active", "inactive"]),
-            update_cache=dict(default="no", aliases=["update-cache"], type='bool')
+            update_ports=dict(aliases=["update_cache"], default="no", type='bool'),
+            variant=dict(aliases=["variants"], default=None, type='str')
         )
     )
 
@@ -206,22 +231,24 @@ def main():
 
     p = module.params
 
-    if p["update_cache"]:
+    if p["update_ports"]:
-        update_package_db(module, port_path)
+        sync_ports(module, port_path)
 
-    pkgs = p["name"].split(",")
+    pkgs = p["name"]
+
+    variant = p["variant"]
 
     if p["state"] in ["present", "installed"]:
-        install_packages(module, port_path, pkgs)
+        install_ports(module, port_path, pkgs, variant)
 
     elif p["state"] in ["absent", "removed"]:
-        remove_packages(module, port_path, pkgs)
+        remove_ports(module, port_path, pkgs)
 
     elif p["state"] == "active":
-        activate_packages(module, port_path, pkgs)
+        activate_ports(module, port_path, pkgs)
 
     elif p["state"] == "inactive":
-        deactivate_packages(module, port_path, pkgs)
+        deactivate_ports(module, port_path, pkgs)
 
 
 if __name__ == '__main__':

test/sanity/validate-modules/ignore.txt

@@ -969,7 +969,6 @@ lib/ansible/modules/packaging/os/flatpak_remote.py E210
 lib/ansible/modules/packaging/os/homebrew.py E326
 lib/ansible/modules/packaging/os/homebrew_cask.py E326
 lib/ansible/modules/packaging/os/layman.py E322
-lib/ansible/modules/packaging/os/macports.py E322
 lib/ansible/modules/packaging/os/macports.py E326
 lib/ansible/modules/packaging/os/openbsd_pkg.py E326
 lib/ansible/modules/packaging/os/opkg.py E322