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

@@ -36,11 +36,13 @@ description:
      - Before version 2.0, comments are discarded when the source file is read, and therefore will not show up in the destination file.
 version_added: "0.9"
 options:
-  dest:
+  path:
     description:
-      - Path to the INI-style file; this file is created if required
+      - Path to the INI-style file; this file is created if required.
+      - Before 2.3 this option was only usable as I(dest).
     required: true
     default: null
+    aliases: ['dest']
   section:
     description:
       - Section name in INI file. This is added if C(state=present) automatically when
@@ -94,15 +96,18 @@ options:
 notes:
    - While it is possible to add an I(option) without specifying a I(value), this makes
      no sense.
+   - As of Ansible 2.3, the I(dest) option has been changed to I(path) as default, but
+     I(dest) still works as well.
 author:
     - "Jan-Piet Mens (@jpmens)"
     - "Ales Nosek (@noseka1)"
 '''
 
 EXAMPLES = '''
-# Ensure "fav=lemonade is in section "[drinks]" in specified file
-- ini_file:
-    dest: /etc/conf
+# Before 2.3, option 'dest' was used instead of 'path'
+- name: Ensure "fav=lemonade is in section "[drinks]" in specified file
+  ini_file:
+    path: /etc/conf
     section: drinks
     option: fav
     value: lemonade
@@ -110,7 +115,7 @@ EXAMPLES = '''
     backup: yes
 
 - ini_file:
-    dest: /etc/anotherconf
+    path: /etc/anotherconf
     section: drinks
     option: temperature
     value: cold
@@ -120,6 +125,9 @@ EXAMPLES = '''
 import os
 import re
 
+# import module snippets
+from ansible.module_utils.basic import AnsibleModule
+
 # ==============================================================
 # match_opt
 
@@ -258,7 +266,7 @@ def main():
 
     module = AnsibleModule(
         argument_spec = dict(
-            dest = dict(required=True),
+            path = dict(required=True, aliases=['dest'], type='path'),
             section = dict(required=True),
             option = dict(required=False),
             value = dict(required=False),
@@ -271,7 +279,7 @@ def main():
         supports_check_mode = True
     )
 
-    dest = os.path.expanduser(module.params['dest'])
+    path = os.path.expanduser(module.params['path'])
     section = module.params['section']
     option = module.params['option']
     value = module.params['value']
@@ -280,20 +288,18 @@ def main():
     no_extra_spaces = module.params['no_extra_spaces']
     create = module.params['create']
 
-    (changed,backup_file,diff,msg) = do_ini(module, dest, section, option, value, state, backup, no_extra_spaces, create)
+    (changed,backup_file,diff,msg) = do_ini(module, path, section, option, value, state, backup, no_extra_spaces, create)
 
-    if not module.check_mode and os.path.exists(dest):
+    if not module.check_mode and os.path.exists(path):
         file_args = module.load_file_common_arguments(module.params)
         changed = module.set_fs_attributes_if_different(file_args, changed)
 
-    results = { 'changed': changed, 'msg': msg, 'dest': dest, 'diff': diff }
+    results = { 'changed': changed, 'msg': msg, 'path': path, 'diff': diff }
     if backup_file is not None:
         results['backup_file'] = backup_file
 
     # Mission complete
     module.exit_json(**results)
 
-# import module snippets
-from ansible.module_utils.basic import *
 if __name__ == '__main__':
     main()