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/acl.py

@@ -27,12 +27,12 @@ short_description: Sets and retrieves file ACL information.
 description:
     - Sets and retrieves file ACL information.
 options:
-  name:
+  path:
     required: true
     default: null
     description:
       - The full path of the file or object.
-    aliases: ['path']
+    aliases: ['name']
 
   state:
     required: false
@@ -54,7 +54,7 @@ options:
     default: no
     choices: [ 'yes', 'no' ]
     description:
-      - if the target is a directory, setting this to yes will make it the default acl for entities created inside the directory. It causes an error if name is a file.
+      - if the target is a directory, setting this to yes will make it the default acl for entities created inside the directory. It causes an error if path is a file.
 
   entity:
     version_added: "1.5"
@@ -70,7 +70,6 @@ options:
     description:
       - the entity type of the ACL to apply, see setfacl documentation for more info.
 
-
   permissions:
     version_added: "1.5"
     required: false
@@ -97,12 +96,13 @@ author:
 notes:
     - The "acl" module requires that acls are enabled on the target filesystem and that the setfacl and getfacl binaries are installed.
     - As of Ansible 2.0, this module only supports Linux distributions.
+    - As of Ansible 2.3, the I(name) option has been changed to I(path) as default, but I(name) still works as well.
 '''
 
 EXAMPLES = '''
 # Grant user Joe read access to a file
 - acl:
-    name: /etc/foo.conf
+    path: /etc/foo.conf
     entity: joe
     etype: user
     permissions: r
@@ -110,14 +110,14 @@ EXAMPLES = '''
 
 # Removes the acl for Joe on a specific file
 - acl:
-    name: /etc/foo.conf
+    path: /etc/foo.conf
     entity: joe
     etype: user
     state: absent
 
 # Sets default acl for joe on foo.d
 - acl:
-    name: /etc/foo.d
+    path: /etc/foo.d
     entity: joe
     etype: user
     permissions: rw
@@ -126,13 +126,13 @@ EXAMPLES = '''
 
 # Same as previous but using entry shorthand
 - acl:
-    name: /etc/foo.d
+    path: /etc/foo.d
     entry: "default:user:joe:rw-"
     state: present
 
 # Obtain the acl for a specific file
 - acl:
-    name: /etc/foo.conf
+    path: /etc/foo.conf
   register: acl_info
 '''
 
@@ -144,6 +144,10 @@ acl:
     sample: [ "user::rwx", "group::rwx", "other::rwx" ]
 '''
 
+import os
+
+# import module snippets
+from ansible.module_utils.basic import AnsibleModule, get_platform
 
 def split_entry(entry):
     ''' splits entry and ensures normalized return'''
@@ -258,7 +262,7 @@ def run_acl(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'),
             entry=dict(required=False, type='str'),
             entity=dict(required=False, type='str', default=''),
             etype=dict(
@@ -284,7 +288,7 @@ def main():
     if get_platform().lower() not in ['linux', 'freebsd']:
         module.fail_json(msg="The acl module is not available on this system.")
 
-    path = module.params.get('name')
+    path = module.params.get('path')
     entry = module.params.get('entry')
     entity = module.params.get('entity')
     etype = module.params.get('etype')
@@ -369,8 +373,5 @@ def main():
 
     module.exit_json(changed=changed, msg=msg, acl=acl)
 
-# import module snippets
-from ansible.module_utils.basic import *
-
 if __name__ == '__main__':
     main()