Consistent path attribute for file-related modules

Not all file-related modules consistently use "path" as the attribute to specify a single filename, some use "dest", others use "name". Most do have aliases for either "name" or "destfile".

This change makes "path" the default attribute for (single) file-related modules, but also adds "dest" and "name" as aliases, so that people can use a consistent way of attributing paths, but also to ensure backward compatibility with existing playbooks.

NOTE: The reason for changing this, is that it makes Ansible needlessly harder to use if you have to remember that e.g. the xattr module requires the name attribute, the lineinfile module requires a dest attribute, and the stat module requires a path attribute.

lib/ansible/modules/files/xattr.py

@@ -27,12 +27,13 @@ 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:
-  name:
+  path:
     required: true
     default: None
-    aliases: ['path']
+    aliases: ['name']
     description:
-      - The full path of the file/object to get the facts of
+      - The full path of the file/object to get the facts of.
+      - Before 2.3 this option was only usable as I(name).
   key:
     required: false
     default: None
@@ -61,6 +62,8 @@ options:
     description:
       - if yes, dereferences symlinks and sets/gets attributes on symlink target,
         otherwise acts on symlink itself.
+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: "Brian Coca (@bcoca)"
 '''
@@ -68,7 +71,7 @@ author: "Brian Coca (@bcoca)"
 EXAMPLES = '''
 # Obtain the extended attributes  of /etc/foo.conf
 - xattr:
-    name: /etc/foo.conf
+    path: /etc/foo.conf
 
 # Sets the key 'foo' to value 'bar'
 - xattr:
@@ -78,7 +81,7 @@ EXAMPLES = '''
 
 # Removes the key 'foo'
 - xattr:
-    name: /etc/foo.conf
+    path: /etc/foo.conf
     key: user.foo
     state: absent
 '''
@@ -87,6 +90,10 @@ import operator
 import re
 import os
 
+# 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):
     cmd = [ module.get_bin_path('getfattr', True) ]
     # prevents warning and not sure why it's not default
@@ -156,7 +163,7 @@ def _run_xattr(module,cmd,check_rc=True):
 def main():
     module = AnsibleModule(
         argument_spec = dict(
-            name = dict(required=True, aliases=['path'], type='path'),
+            path = dict(required=True, aliases=['name'], type='path'),
             key = dict(required=False, default=None, type='str'),
             value = dict(required=False, default=None, type='str'),
             state = dict(required=False, default='read', choices=[ 'read', 'present', 'all', 'keys', 'absent' ], type='str'),
@@ -164,7 +171,7 @@ def main():
         ),
         supports_check_mode=True,
     )
-    path = module.params.get('name')
+    path = module.params.get('path')
     key = module.params.get('key')
     value = module.params.get('value')
     state = module.params.get('state')
@@ -214,8 +221,5 @@ def main():
 
     module.exit_json(changed=changed, msg=msg, xattr=res)
 
-# import module snippets
-from ansible.module_utils.basic import AnsibleModule
-from ansible.module_utils.pycompat24 import get_exception
 if __name__ == '__main__':
     main()