apt: PEP8 compliancy and documentation changes (#33425)

This PR includes:
- PEP compliancy changes
- Documentation changes

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

@@ -1,21 +1,19 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
 
-# (c) 2012, Flowroute LLC
+# Copyright: (c) 2012, Flowroute LLC
 # Written by Matthew Williams <matthew@flowroute.com>
 # Based on yum module written by Seth Vidal <skvidal at fedoraproject.org>
-#
+
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
 from __future__ import absolute_import, division, print_function
 __metaclass__ = type
 
-
 ANSIBLE_METADATA = {'metadata_version': '1.1',
                     'status': ['stableinterface'],
                     'supported_by': 'core'}
 
-
 DOCUMENTATION = '''
 ---
 module: apt
@@ -28,79 +26,65 @@ options:
     description:
       - A list of package names, like C(foo), or package specifier with version, like C(foo=1.0).
         Name wildcards (fnmatch) like C(apt*) and version wildcards like C(foo=1.0*) are also supported.
-    required: false
+    aliases: [ package, pkg ]
-    default: null
-    aliases: [ 'pkg', 'package' ]
   state:
     description:
       - Indicates the desired package state. C(latest) ensures that the latest version is installed. C(build-dep) ensures the package build dependencies
         are installed.
-    required: false
     default: present
-    choices: [ "latest", "absent", "present", "build-dep" ]
+    choices: [ absent, build-dep, latest, present ]
   update_cache:
     description:
       - 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.
-    required: false
+    type: bool
-    default: no
+    default: 'no'
-    choices: [ "yes", "no" ]
   cache_valid_time:
     description:
       - Update the apt cache if its older than the I(cache_valid_time). This option is set in seconds.
         As of Ansible 2.4, this implicitly sets I(update_cache) if set.
-    required: false
     default: 0
   purge:
     description:
      - Will force purging of configuration files if the module state is set to I(absent).
-    required: false
+    type: bool
-    default: no
+    default: 'no'
-    choices: [ "yes", "no" ]
   default_release:
     description:
       - Corresponds to the C(-t) option for I(apt) and sets pin priorities
-    required: false
-    default: null
   install_recommends:
     description:
       - Corresponds to the C(--no-install-recommends) option for I(apt). C(yes) installs recommended packages.  C(no) does not install
         recommended packages. By default, Ansible will use the same defaults as the operating system. Suggested packages are never installed.
-    required: false
+    type: bool
-    default: null
-    choices: [ "yes", "no" ]
   force:
     description:
       - 'Corresponds to the C(--force-yes) to I(apt-get) and implies C(allow_unauthenticated: yes)'
       - 'This option *is not* the equivalent of passing the C(-f) flag to I(apt-get) on the command line'
       - '**This is a destructive operation with the potential to destroy your system, and it should almost never be used.**
          Please also see C(man apt-get) for more information.'
-    required: false
+    type: bool
-    default: "no"
+    default: 'no'
-    choices: [ "yes", "no" ]
   allow_unauthenticated:
     description:
       - Ignore if packages cannot be authenticated. This is useful for bootstrapping environments that manage their own apt-key setup.
-    required: false
+    type: bool
-    default: "no"
+    default: 'no'
-    choices: [ "yes", "no" ]
     version_added: "2.1"
   upgrade:
     description:
-      - 'If yes or safe, performs an aptitude safe-upgrade.'
+      - If yes or safe, performs an aptitude safe-upgrade.
-      - 'If full, performs an aptitude full-upgrade.'
+      - If full, performs an aptitude full-upgrade.
-      - 'If dist, performs an apt-get dist-upgrade.'
+      - If dist, performs an apt-get dist-upgrade.
       - 'Note: This does not upgrade a specific package, use state=latest for that.'
       - 'Note: Since 2.4, apt-get is used as a fall-back if aptitude is not present.'
     version_added: "1.1"
-    required: false
+    choices: [ dist, full, 'no', safe, 'yes' ]
-    default: "no"
+    default: 'no'
-    choices: [ "no", "yes", "safe", "full", "dist"]
   dpkg_options:
     description:
       - Add dpkg options to apt command. Defaults to '-o "Dpkg::Options::=--force-confdef" -o "Dpkg::Options::=--force-confold"'
       - Options should be supplied as comma separated list
-    required: false
+    default: force-confdef,force-confold
-    default: 'force-confdef,force-confold'
   deb:
      description:
        - Path to a .deb package on the remote machine.
@@ -111,28 +95,26 @@ options:
     description:
       - If C(yes), remove unused dependency packages for all module states except I(build-dep). It can also be used as the only option.
       - Previous to version 2.4, autoclean was also an alias for autoremove, now it is its own separate command. See documentation for further information.
-    required: false
+    type: bool
-    default: no
+    default: 'no'
-    choices: [ "yes", "no" ]
     version_added: "2.1"
   autoclean:
     description:
       - If C(yes), cleans the local repository of retrieved package files that can no longer be downloaded.
-    required: false
+    type: bool
-    default: no
+    default: 'no'
-    choices: [ "yes", "no" ]
     version_added: "2.4"
   only_upgrade:
     description:
       - Only upgrade a package if it is already installed.
-    required: false
+    type: bool
-    default: false
+    default: 'no'
     version_added: "2.1"
   force_apt_get:
     description:
       - Force usage of apt-get instead of aptitude
-    required: false
+    type: bool
-    default: false
+    default: 'no'
     version_added: "2.4"
 requirements:
    - python-apt (python 2)
@@ -340,7 +322,7 @@ def package_status(m, pkgname, version, cache, state):
         # state fields not directly accessible from the
         # higher-level apt.package.Package object.
         pkg = cache[pkgname]
-        ll_pkg = cache._cache[pkgname] # the low-level package object
+        ll_pkg = cache._cache[pkgname]  # the low-level package object
     except KeyError:
         if state == 'install':
             try:
@@ -371,7 +353,7 @@ def package_status(m, pkgname, version, cache, state):
 
     try:
         package_is_installed = ll_pkg.current_state == apt_pkg.CURSTATE_INSTALLED
-    except AttributeError: # python-apt 0.7.X has very weak low-level object
+    except AttributeError:  # python-apt 0.7.X has very weak low-level object
         try:
             # might not be necessary as python-apt post-0.7.X should have current_state property
             package_is_installed = pkg.is_installed
@@ -623,7 +605,7 @@ def install_deb(m, debs, cache, force, install_recommends, allow_unauthenticated
         changed = retvals.get('changed', False)
 
     if pkgs_to_install:
-        options = ' '.join(["--%s"% x for x in dpkg_options.split(",")])
+        options = ' '.join(["--%s" % x for x in dpkg_options.split(",")])
         if m.check_mode:
             options += " --simulate"
         if force:
@@ -811,7 +793,7 @@ def download(module, deb):
             data = to_bytes(data, errors='surrogate_or_strict')
 
             if len(data) < 1:
-                break # End of file, break while loop
+                break  # End of file, break while loop
 
             f.write(data)
         f.close()
@@ -876,26 +858,26 @@ def get_cache(module):
 def main():
     module = AnsibleModule(
         argument_spec=dict(
-            state=dict(default='present', choices=['installed', 'latest', 'removed', 'absent', 'present', 'build-dep']),
+            state=dict(type='str', default='present', choices=['absent', 'build-dep', 'installed', 'latest', 'present', 'removed', 'present']),
-            update_cache=dict(aliases=['update-cache'], type='bool'),
+            update_cache=dict(type='bool', aliases=['update-cache']),
             cache_valid_time=dict(type='int', default=0),
-            purge=dict(default=False, type='bool'),
+            purge=dict(type='bool', default=False),
-            package=dict(default=None, aliases=['pkg', 'name'], type='list'),
+            package=dict(type='list', aliases=['pkg', 'name']),
-            deb=dict(default=None, type='path'),
+            deb=dict(type='path'),
-            default_release=dict(default=None, aliases=['default-release']),
+            default_release=dict(type='str', aliases=['default-release']),
-            install_recommends=dict(default=None, aliases=['install-recommends'], type='bool'),
+            install_recommends=dict(type='bool', aliases=['install-recommends']),
-            force=dict(default='no', type='bool'),
+            force=dict(type='bool', default=False),
-            upgrade=dict(choices=['no', 'yes', 'safe', 'full', 'dist']),
+            upgrade=dict(type='str', choices=['dist', 'full', 'no', 'safe', 'yes']),
-            dpkg_options=dict(default=DPKG_OPTIONS),
+            dpkg_options=dict(type='str', default=DPKG_OPTIONS),
-            autoremove=dict(type='bool', default='no'),
+            autoremove=dict(type='bool', default=False),
-            autoclean=dict(type='bool', default='no'),
+            autoclean=dict(type='bool', default=False),
             only_upgrade=dict(type='bool', default=False),
             force_apt_get=dict(type='bool', default=False),
-            allow_unauthenticated=dict(default='no', aliases=['allow-unauthenticated'], type='bool'),
+            allow_unauthenticated=dict(type='bool', default=False, aliases=['allow-unauthenticated']),
         ),
-        mutually_exclusive=[['package', 'upgrade', 'deb']],
+        mutually_exclusive=[['deb', 'package', 'upgrade']],
-        required_one_of=[['package', 'upgrade', 'update_cache', 'deb', 'autoremove']],
+        required_one_of=[['autoremove', 'deb', 'package', 'update_cache', 'upgrade']],
-        supports_check_mode=True
+        supports_check_mode=True,
     )
 
     module.run_command_environ_update = APT_ENV_VARS

test/sanity/pep8/legacy-files.txt

@@ -258,7 +258,6 @@ lib/ansible/modules/packaging/language/gem.py
 lib/ansible/modules/packaging/language/maven_artifact.py
 lib/ansible/modules/packaging/language/pear.py
 lib/ansible/modules/packaging/os/apk.py
-lib/ansible/modules/packaging/os/apt.py
 lib/ansible/modules/packaging/os/apt_key.py
 lib/ansible/modules/packaging/os/apt_repository.py
 lib/ansible/modules/packaging/os/dpkg_selections.py