win_chocolatey: Clean up parameter handling (#21533)

Changes include:

- Use Get-AnsibleParam with -type/-validateset
- Replace $result PSObject with normal hash
- Deprecate 'upgrade' parameter by using state=latest

lib/ansible/modules/windows/win_chocolatey.ps1

@@ -20,36 +20,39 @@
 # WANT_JSON
 # POWERSHELL_COMMON
 
-$params = Parse-Args $args;
+$result = @{
-$result = New-Object PSObject;
+    changed = $false
-Set-Attr $result "changed" $false;
-
-$package = Get-Attr -obj $params -name name -failifempty $true -emptyattributefailmessage "missing required argument: name"
-$force = Get-Attr -obj $params -name force -default "false" | ConvertTo-Bool
-$upgrade = Get-Attr -obj $params -name upgrade -default "false" | ConvertTo-Bool
-$version = Get-Attr -obj $params -name version -default $null
-
-$source = Get-Attr -obj $params -name source -default $null
-if ($source) {$source = $source.Tolower()}
-
-$showlog = Get-Attr -obj $params -name showlog -default "false" | ConvertTo-Bool
-$state = Get-Attr -obj $params -name state -default "present"
-
-$installargs = Get-Attr -obj $params -name install_args -default $null
-$packageparams = Get-Attr -obj $params -name params -default $null
-$allowemptychecksums = Get-Attr -obj $params -name allow_empty_checksums -default "false" | ConvertTo-Bool
-$ignorechecksums = Get-Attr -obj $params -name ignore_checksums -default "false" | ConvertTo-Bool
-$ignoredependencies = Get-Attr -obj $params -name ignore_dependencies -default "false" | ConvertTo-Bool
-
-# as of chocolatey 0.9.10, nonzero success exit codes can be returned
-# see https://github.com/chocolatey/choco/issues/512#issuecomment-214284461
-$successexitcodes = (0,1605,1614,1641,3010)
-
-if ("present","absent" -notcontains $state)
-{
-    Fail-Json $result "state is $state; must be present or absent"
 }
 
+$params = Parse-Args $args
+
+$package = Get-AnsibleParam -obj $params -name "name" -type "str" -failifempty $true
+$force = Get-AnsibleParam -obj $params -name "force" -type "bool" -default $false
+$upgrade = Get-AnsibleParam -obj $params -name "upgrade" -type "bool" -default $false
+$version = Get-AnsibleParam -obj $params -name "version" -type "str"
+$source = Get-AnsibleParam -obj $params -name "source" -type "str"
+$showlog = Get-AnsibleParam -obj $params -name "showlog" -type "bool" -default $false
+$state = Get-AnsibleParam -obj $params -name "state" -type "str" -default "present" -validateset "present","absent","latest"
+$installargs = Get-AnsibleParam -obj $params -name "install_args" -type "str"
+$packageparams = Get-AnsibleParam -obj $params -name "params" -type "str"
+$allowemptychecksums = Get-AnsibleParam -obj $params -name "allow_empty_checksums" -type "bool" -default $false
+$ignorechecksums = Get-AnsibleParam -obj $params -name "ignore_checksums" -type "bool" -default $false
+$ignoredependencies = Get-AnsibleParam -obj $params -name "ignore_dependencies" -type "bool" -default $false
+
+if ($source) {$source = $source.Tolower()}
+
+if ($upgrade)
+{
+    Add-DeprecateWarning $result "Parameter upgrade=yes is replaced with state=latest"
+    if ($state -eq "present")
+{
+        $state = "latest"
+    }
+}
+
+# As of chocolatey 0.9.10, nonzero success exit codes can be returned
+# See https://github.com/chocolatey/choco/issues/512#issuecomment-214284461
+$successexitcodes = (0,1605,1614,1641,3010)
 
 Function Chocolatey-Install-Upgrade
 {
@@ -60,24 +63,28 @@ Function Chocolatey-Install-Upgrade
     $ChocoAlreadyInstalled = get-command choco -ErrorAction 0
     if ($ChocoAlreadyInstalled -eq $null)
     {
+
         #We need to install chocolatey
         $install_output = (new-object net.webclient).DownloadString("https://chocolatey.org/install.ps1") | powershell -
         if ($LASTEXITCODE -ne 0)
         {
-            Set-Attr $result "choco_bootstrap_output" $install_output
+            $result.choco_bootstrap_output = $install_output
             Fail-Json $result "Chocolatey bootstrap installation failed."
         }
         $result.changed = $true
         $script:executable = "C:\ProgramData\chocolatey\bin\choco.exe"
+
     }
     else
     {
+
         $script:executable = "choco.exe"
 
         if ([Version](choco --version) -lt [Version]'0.9.9')
         {
-            Choco-Upgrade chocolatey 
+            Choco-Upgrade chocolatey
         }
+
     }
 }
 
@@ -85,35 +92,36 @@ Function Chocolatey-Install-Upgrade
 Function Choco-IsInstalled
 {
     [CmdletBinding()]
-    
+
     param(
         [Parameter(Mandatory=$true, Position=1)]
         [string]$package
     )
 
     $cmd = "$executable list --local-only $package"
-    $results = invoke-expression $cmd
+    $output = invoke-expression $cmd
 
+    $result.rc = $LastExitCode
     if ($LastExitCode -ne 0)
     {
-        Set-Attr $result "choco_error_cmd" $cmd
+        $result.choco_error_cmd = $cmd
-        Set-Attr $result "choco_error_log" "$results"
+        $result.choco_error_log = $output
-        
+
-        Throw "Error checking installation status for $package" 
+        Throw "Error checking installation status for $package"
-    } 
+    }
-    
+
     If ("$results" -match "$package .* (\d+) packages installed.")
     {
         return $matches[1] -gt 0
     }
-    
+
-    $false
+    return $false
 }
 
-Function Choco-Upgrade 
+Function Choco-Upgrade
 {
     [CmdletBinding()]
-    
+
     param(
         [Parameter(Mandatory=$true, Position=1)]
         [string]$package,
@@ -171,7 +179,7 @@ Function Choco-Upgrade
     {
         $cmd += " --allow-empty-checksums"
     }
-    
+
     if ($ignorechecksums)
     {
         $cmd += " --ignore-checksums"
@@ -182,13 +190,14 @@ Function Choco-Upgrade
         $cmd += " -ignoredependencies"
     }
 
-    $results = invoke-expression $cmd
+    $output = invoke-expression $cmd
 
+    $result.rc = $LastExitCode
     if ($LastExitCode -notin $successexitcodes)
     {
-        Set-Attr $result "choco_error_cmd" $cmd
+        $result.choco_error_cmd = $cmd
-        Set-Attr $result "choco_error_log" "$results"
+        $result.choco_error_log = $output
-        Throw "Error installing $package" 
+        Throw "Error installing $package"
     }
 
     if ("$results" -match ' upgraded (\d+)/\d+ package\(s\)\. ')
@@ -200,10 +209,10 @@ Function Choco-Upgrade
     }
 }
 
-Function Choco-Install 
+Function Choco-Install
 {
     [CmdletBinding()]
-    
+
     param(
         [Parameter(Mandatory=$true, Position=1)]
         [string]$package,
@@ -227,22 +236,9 @@ Function Choco-Install
         [bool]$ignoredependencies
     )
 
-    if (Choco-IsInstalled $package)
+    if ((Choco-IsInstalled $package) -and -not $force)
     {
-        if ($upgrade)
+        return
-        {
-            Choco-Upgrade -package $package -version $version -source $source -force $force `
-                -installargs $installargs -packageparams $packageparams `
-                -allowemptychecksums $allowemptychecksums -ignorechecksums $ignorechecksums `
-                -ignoredependencies $ignoredependencies
-
-            return
-        }
-
-        if (-not $force)
-        {
-            return
-        }
     }
 
     $cmd = "$executable install -dv -y $package"
@@ -276,7 +272,7 @@ Function Choco-Install
     {
         $cmd += " --allow-empty-checksums"
     }
-    
+
     if ($ignorechecksums)
     {
         $cmd += " --ignore-checksums"
@@ -287,22 +283,23 @@ Function Choco-Install
         $cmd += " -ignoredependencies"
     }
 
-    $results = invoke-expression $cmd
+    $output = invoke-expression $cmd
 
+    $result.rc = $LastExitCode
     if ($LastExitCode -notin $successexitcodes)
     {
-        Set-Attr $result "choco_error_cmd" $cmd
+        $result.choco_error_cmd = $cmd
-        Set-Attr $result "choco_error_log" "$results"
+        $result.choco_error_log = $output
-        Throw "Error installing $package" 
+        Throw "Error installing $package"
     }
 
-     $result.changed = $true
+    $result.changed = $true
 }
 
-Function Choco-Uninstall 
+Function Choco-Uninstall
 {
     [CmdletBinding()]
-    
+
     param(
         [Parameter(Mandatory=$true, Position=1)]
         [string]$package,
@@ -334,38 +331,45 @@ Function Choco-Uninstall
         $cmd += " -params '$packageparams'"
     }
 
-    $results = invoke-expression $cmd
+    $output = invoke-expression $cmd
 
+    $result.rc = $LastExitCode
     if ($LastExitCode -notin $successexitcodes)
     {
-        Set-Attr $result "choco_error_cmd" $cmd
+        $result.choco_error_cmd = $cmd
-        Set-Attr $result "choco_error_log" "$results"
+        $result.choco_error_log = $output
-        Throw "Error uninstalling $package" 
+        Throw "Error uninstalling $package"
     }
 
-     $result.changed = $true
+    $result.changed = $true
 }
+
 Try
 {
     Chocolatey-Install-Upgrade
 
     if ($state -eq "present")
     {
-        Choco-Install -package $package -version $version -source $source `
+        Choco-Install -package $package -version $version -source $source -force $force `
-            -force $force -upgrade $upgrade -installargs $installargs `
+            -installargs $installargs -packageparams $packageparams `
-            -packageparams $packageparams -allowemptychecksums $allowemptychecksums `
+            -allowemptychecksums $allowemptychecksums -ignorechecksums $ignorechecksums `
-            -ignorechecksums $ignorechecksums -ignoredependencies $ignoredependencies
+            -ignoredependencies $ignoredependencies
     }
-    else
+    elseif ($state -eq "latest")
+    {
+        Choco-Upgrade -package $package -version $version -source $source -force $force `
+            -installargs $installargs -packageparams $packageparams `
+            -allowemptychecksums $allowemptychecksums -ignorechecksums $ignorechecksums `
+            -ignoredependencies $ignoredependencies
+    }
+    elseif ($state -eq "absent")
     {
         Choco-Uninstall -package $package -version $version -force $force
     }
 
-    Exit-Json $result;
+    Exit-Json $result
 }
 Catch
 {
-     Fail-Json $result $_.Exception.Message
+    Fail-Json $result $_.Exception.Message
 }
-
-

lib/ansible/modules/windows/win_chocolatey.py

@@ -31,7 +31,9 @@ module: win_chocolatey
 version_added: "1.9"
 short_description: Installs packages using chocolatey
 description:
-    - Installs packages using Chocolatey (http://chocolatey.org/). If Chocolatey is missing from the system, the module will install it. List of packages can be found at http://chocolatey.org/packages
+    - Installs packages using Chocolatey (U(http://chocolatey.org/)).
+    - If Chocolatey is missing from the system, the module will install it.
+    - List of packages can be found at U(http://chocolatey.org/packages)
 options:
   name:
     description:
@@ -43,25 +45,29 @@ options:
     choices:
       - present
       - absent
+      - latest
     default: present
   force:
     description:
-      - Forces install of the package (even if it already exists). Using Force will cause ansible to always report that a change was made
+      - Forces install of the package (even if it already exists).
+      - Using C(force) will cause ansible to always report that a change was made
     choices:
       - yes
       - no
     default: no
   upgrade:
     description:
-      - If package is already installed it, try to upgrade to the latest version or to the specified version
+      - If package is already installed it, try to upgrade to the latest version or to the specified version.
+      - As of Ansible v2.3 this is deprecated, set parameter C(state) to "latest" for the same result.
+    version_removed: '2.3'
     choices:
       - yes
       - no
     default: no
   version:
     description:
-      - Specific version of the package to be installed
+      - Specific version of the package to be installed.
-      - Ignored when state == 'absent'
+      - Ignored when C(state) is set to "absent".
   source:
     description:
       - Specify source rather than using default chocolatey repository
@@ -76,13 +82,11 @@ options:
   allow_empty_checksums:
     description:
       - Allow empty Checksums to be used
-    require: false
     default: false
     version_added: '2.2'
   ignore_checksums:
     description:
       - Ignore Checksums
-    require: false
     default: false
     version_added: '2.2'
   ignore_dependencies:

test/sanity/pep8/legacy-files.txt

@@ -219,7 +219,6 @@ lib/ansible/modules/web_infrastructure/jira.py
 lib/ansible/modules/web_infrastructure/nginx_status_facts.py
 lib/ansible/modules/windows/win_acl.py
 lib/ansible/modules/windows/win_acl_inheritance.py
-lib/ansible/modules/windows/win_chocolatey.py
 lib/ansible/modules/windows/win_command.py
 lib/ansible/modules/windows/win_feature.py
 lib/ansible/modules/windows/win_lineinfile.py