feat(pkgin): add support for installation of full versioned package names (#1256)

* * pkgin query_package(..) understands now also package name with version (my-package-1.2nb123456). * pkgin query_package(..) will distinct between not-installed and not-found packages. * pkgin install_package(..) fails with proper error if a non-existing package is attempted to be installed.

* fixup ansibot comments

* add changelog fragment

* add example

* use more pythonic condition

Co-authored-by: Andrew Klychkov <aaklychkov@mail.ru>

* remove extra dot between description and link to PR

Co-authored-by: Andrew Klychkov <aaklychkov@mail.ru>

* fix file extension of changelog fragment

* add pkgin unit tests for query_package function

* fix pep8 issues

* use enum Flag instead mix of strings, bools and None as return value

* use IntEnum instead Flag to support Python versions >= 2.6

* fix pep8 and pylint errors

* use regular class instead enum to avoid issues with older Python releases

* fix comment

* remove the combined package state since without an IntFlag or Flag the usage of it would require to use logical operators

Co-authored-by: Erik van Nooijen <eric.vannooijen@tomtom.com>
Co-authored-by: Andrew Klychkov <aaklychkov@mail.ru>

plugins/modules/packaging/os/pkgin.py

@@ -77,6 +77,11 @@ EXAMPLES = '''
     name: foo
     state: present
 
+- name: Install specific version of foo package
+  community.general.pkgin:
+    name: foo-2.0.1
+    state: present
+
 - name: Update cache and install foo package
   community.general.pkgin:
     name: foo
@@ -120,13 +125,15 @@ import re
 from ansible.module_utils.basic import AnsibleModule
 
 
-def query_package(module, name):
-    """Search for the package by name.
+class PackageState(object):
+    PRESENT = 1
+    NOT_INSTALLED = 2
+    OUTDATED = 4
+    NOT_FOUND = 8
 
-    Possible return values:
-    * "present"  - installed, no upgrade needed
-    * "outdated" - installed, but can be upgraded
-    * False      - not installed or not found
+
+def query_package(module, name):
+    """Search for the package by name and return state of the package.
     """
 
     # test whether '-p' (parsable) flag is supported.
@@ -172,20 +179,24 @@ def query_package(module, name):
             # Grab matched string
             pkgname_without_version = pkg_search_obj.group(1)
 
-            if name != pkgname_without_version:
+            if name not in (pkgname_with_version, pkgname_without_version):
                 continue
 
             # The package was found; now return its state
             if raw_state == '<':
-                return 'outdated'
+                return PackageState.OUTDATED
             elif raw_state == '=' or raw_state == '>':
-                return 'present'
+                return PackageState.PRESENT
             else:
-                return False
+                # Package found but not installed
+                return PackageState.NOT_INSTALLED
             # no fall-through
 
-        # No packages were matched, so return False
-        return False
+        # No packages were matched
+        return PackageState.NOT_FOUND
+
+    # Search failed
+    return PackageState.NOT_FOUND
 
 
 def format_action_message(module, action, count):
@@ -233,13 +244,13 @@ def remove_packages(module, packages):
     # Using a for loop in case of error, we can report the package that failed
     for package in packages:
         # Query the package first, to see if we even need to remove
-        if not query_package(module, package):
+        if query_package(module, package) in [PackageState.NOT_INSTALLED, PackageState.NOT_FOUND]:
             continue
 
         rc, out, err = module.run_command(
             format_pkgin_command(module, "remove", package))
 
-        if not module.check_mode and query_package(module, package):
+        if not module.check_mode and query_package(module, package) in [PackageState.PRESENT, PackageState.OUTDATED]:
             module.fail_json(msg="failed to remove %s: %s" % (package, out))
 
         remove_c += 1
@@ -255,13 +266,16 @@ def install_packages(module, packages):
     install_c = 0
 
     for package in packages:
-        if query_package(module, package):
+        query_result = query_package(module, package)
+        if query_result in [PackageState.PRESENT, PackageState.OUTDATED]:
             continue
+        elif query_result is PackageState.NOT_FOUND:
+            module.fail_json(msg="failed to find package %s for installation" % package)
 
         rc, out, err = module.run_command(
             format_pkgin_command(module, "install", package))
 
-        if not module.check_mode and not query_package(module, package):
+        if not module.check_mode and not query_package(module, package) in [PackageState.PRESENT, PackageState.OUTDATED]:
             module.fail_json(msg="failed to install %s: %s" % (package, out))
 
         install_c += 1