xattr: PEP8 compliancy, pylint and docs (#30861)

This PR includes;
- PEP8 compliancy fixes
- pylint fixes
- Documentation updates

lib/ansible/modules/files/xattr.py

@@ -1,4 +1,5 @@
 #!/usr/bin/python
+
 # Copyright: (c) 2017, Ansible Project
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
@@ -9,37 +10,28 @@ ANSIBLE_METADATA = {'metadata_version': '1.1',
                     'status': ['stableinterface'],
                     'supported_by': 'community'}
 
-
 DOCUMENTATION = '''
 ---
 module: xattr
 version_added: "1.3"
-short_description: set/retrieve extended attributes
+short_description: Manage user defined extended attributes
 description:
      - Manages filesystem user defined extended attributes, requires that they are enabled
        on the target filesystem and that the setfattr/getfattr utilities are present.
 options:
   path:
-    required: true
-    default: None
-    aliases: ['name']
     description:
       - The full path of the file/object to get the facts of.
       - Before 2.3 this option was only usable as I(name).
+    aliases: [ name ]
+    required: true
   key:
-    required: false
-    default: None
     description:
-      - The name of a specific Extended attribute key to set/retrieve
+      - The name of a specific Extended attribute key to set/retrieve.
   value:
-    required: false
-    default: None
     description:
-      - The value to set the named name/key to, it automatically sets the C(state) to 'set'
+      - The value to set the named name/key to, it automatically sets the C(state) to 'set'.
   state:
-    required: false
-    default: read
-    choices: [ 'read', 'present', 'all', 'keys', 'absent' ]
     description:
       - defines which state you want to do.
         C(read) retrieves the current value for a C(key) (default)
@@ -47,59 +39,61 @@ options:
         C(all) dumps all data
         C(keys) retrieves all keys
         C(absent) deletes the key
+    choices: [ absent, all, keys, present, read ]
+    default: read
   follow:
-    required: false
-    default: yes
-    choices: [ 'yes', 'no' ]
     description:
-      - if yes, dereferences symlinks and sets/gets attributes on symlink target,
+      - If C(yes), dereferences symlinks and sets/gets attributes on symlink target,
         otherwise acts on symlink itself.
+    type: bool
+    default: 'yes'
 notes:
   - As of Ansible 2.3, the I(name) option has been changed to I(path) as default, but I(name) still works as well.
-
+author:
-author: "Brian Coca (@bcoca)"
+- Brian Coca (@bcoca)
 '''
 
 EXAMPLES = '''
-# Obtain the extended attributes  of /etc/foo.conf
+- name: Obtain the extended attributes  of /etc/foo.conf
-- xattr:
+  xattr:
     path: /etc/foo.conf
 
-# Sets the key 'foo' to value 'bar'
+- name: Sets the key 'foo' to value 'bar'
-- xattr:
+  xattr:
     path: /etc/foo.conf
     key: user.foo
     value: bar
 
-# Removes the key 'foo'
+- name: Removes the key 'foo'
-- xattr:
+  xattr:
     path: /etc/foo.conf
     key: user.foo
     state: absent
 '''
 
 import operator
-import re
 import os
+import re
 
 # import module snippets
 from ansible.module_utils.basic import AnsibleModule
 from ansible.module_utils.pycompat24 import get_exception
 
 
-def get_xattr_keys(module,path,follow):
+def get_xattr_keys(module, path, follow):
-    cmd = [ module.get_bin_path('getfattr', True) ]
+    cmd = [module.get_bin_path('getfattr', True)]
     # prevents warning and not sure why it's not default
     cmd.append('--absolute-names')
     if not follow:
         cmd.append('-h')
     cmd.append(path)
 
-    return _run_xattr(module,cmd)
+    return _run_xattr(module, cmd)
+
 
-def get_xattr(module,path,key,follow):
+def get_xattr(module, path, key, follow):
 
-    cmd = [ module.get_bin_path('getfattr', True) ]
+    cmd = [module.get_bin_path('getfattr', True)]
     # prevents warning and not sure why it's not default
     cmd.append('--absolute-names')
     if not follow:
@@ -110,30 +104,33 @@ def get_xattr(module,path,key,follow):
         cmd.append('-n %s' % key)
     cmd.append(path)
 
-    return _run_xattr(module,cmd,False)
+    return _run_xattr(module, cmd, False)
 
-def set_xattr(module,path,key,value,follow):
 
-    cmd = [ module.get_bin_path('setfattr', True) ]
+def set_xattr(module, path, key, value, follow):
+
+    cmd = [module.get_bin_path('setfattr', True)]
     if not follow:
         cmd.append('-h')
     cmd.append('-n %s' % key)
     cmd.append('-v %s' % value)
     cmd.append(path)
 
-    return _run_xattr(module,cmd)
+    return _run_xattr(module, cmd)
+
 
-def rm_xattr(module,path,key,follow):
+def rm_xattr(module, path, key, follow):
 
-    cmd = [ module.get_bin_path('setfattr', True) ]
+    cmd = [module.get_bin_path('setfattr', True)]
     if not follow:
         cmd.append('-h')
     cmd.append('-x %s' % key)
     cmd.append(path)
 
-    return _run_xattr(module,cmd,False)
+    return _run_xattr(module, cmd, False)
 
-def _run_xattr(module,cmd,check_rc=True):
+
+def _run_xattr(module, cmd, check_rc=True):
 
     try:
         (rc, out, err) = module.run_command(' '.join(cmd), check_rc=check_rc)
@@ -141,7 +138,7 @@ def _run_xattr(module,cmd,check_rc=True):
         e = get_exception()
         module.fail_json(msg="%s!" % e.strerror)
 
-    #result = {'raw': out}
+    # result = {'raw': out}
     result = {}
     for line in out.splitlines():
         if re.match("^#", line) or line == "":
@@ -153,14 +150,15 @@ def _run_xattr(module,cmd,check_rc=True):
             result[line] = ''
     return result
 
+
 def main():
     module = AnsibleModule(
-        argument_spec = dict(
+        argument_spec=dict(
-            path = dict(required=True, aliases=['name'], type='path'),
+            path=dict(type='path', required=True, aliases=['name']),
-            key = dict(required=False, default=None, type='str'),
+            key=dict(type='str'),
-            value = dict(required=False, default=None, type='str'),
+            value=dict(type='str'),
-            state = dict(required=False, default='read', choices=[ 'read', 'present', 'all', 'keys', 'absent' ], type='str'),
+            state=dict(type='str', default='read', choices=['absent', 'all', 'keys', 'present', 'read']),
-            follow = dict(required=False, type='bool', default=True),
+            follow=dict(type='bool', default=True),
         ),
         supports_check_mode=True,
     )
@@ -173,44 +171,42 @@ def main():
     if not os.path.exists(path):
         module.fail_json(msg="path not found or not accessible!")
 
-
+    changed = False
-    changed=False
     msg = ""
     res = {}
 
-    if key is None and state in ['present','absent']:
+    if key is None and state in ['absent', 'present']:
         module.fail_json(msg="%s needs a key parameter" % state)
 
     # All xattr must begin in user namespace
-    if key is not None and not re.match('^user\.',key):
+    if key is not None and not re.match('^user\.', key):
         key = 'user.%s' % key
 
-
     if (state == 'present' or value is not None):
-        current=get_xattr(module,path,key,follow)
+        current = get_xattr(module, path, key, follow)
-        if current is None or not key in current or value != current[key]:
+        if current is None or key not in current or value != current[key]:
             if not module.check_mode:
-                res = set_xattr(module,path,key,value,follow)
+                res = set_xattr(module, path, key, value, follow)
-            changed=True
+            changed = True
-        res=current
+        res = current
-        msg="%s set to %s" % (key, value)
+        msg = "%s set to %s" % (key, value)
     elif state == 'absent':
-        current=get_xattr(module,path,key,follow)
+        current = get_xattr(module, path, key, follow)
         if current is not None and key in current:
             if not module.check_mode:
-                res = rm_xattr(module,path,key,follow)
+                res = rm_xattr(module, path, key, follow)
-            changed=True
+            changed = True
-        res=current
+        res = current
-        msg="%s removed" % (key)
+        msg = "%s removed" % (key)
     elif state == 'keys':
-        res=get_xattr_keys(module,path,follow)
+        res = get_xattr_keys(module, path, follow)
-        msg="returning all keys"
+        msg = "returning all keys"
     elif state == 'all':
-        res=get_xattr(module,path,None,follow)
+        res = get_xattr(module, path, None, follow)
-        msg="dumping all"
+        msg = "dumping all"
     else:
-        res=get_xattr(module,path,key,follow)
+        res = get_xattr(module, path, key, follow)
-        msg="returning %s" % key
+        msg = "returning %s" % key
 
     module.exit_json(changed=changed, msg=msg, xattr=res)
 

test/sanity/pep8/legacy-files.txt

@@ -203,7 +203,6 @@ lib/ansible/modules/files/blockinfile.py
 lib/ansible/modules/files/replace.py
 lib/ansible/modules/files/synchronize.py
 lib/ansible/modules/files/tempfile.py
-lib/ansible/modules/files/xattr.py
 lib/ansible/modules/monitoring/bigpanda.py
 lib/ansible/modules/monitoring/boundary_meter.py
 lib/ansible/modules/monitoring/datadog_event.py