Repository: ansible/ansible

Issue:
stat documentation: mime_type vs mimetype, mime output vs descriptive output
<!---
Verify first that your issue/request is not already reported on GitHub.
Also test if the latest release, and devel branch are affected too.
-->

##### ISSUE TYPE
 - Documentation Report

##### COMPONENT NAME
stat

##### ANSIBLE VERSION
<!--- Paste verbatim output from "ansible --version" between quotes below -->
```
ansible 2.4.3.0
  config file = /etc/ansible/ansible.cfg
  configured module search path = [u'/home/oliver/.ansible/plugins/modules', u'/usr/share/ansible/plugins/modules']
  ansible python module location = /usr/lib/python2.7/dist-packages/ansible
  executable location = /usr/bin/ansible
  python version = 2.7.12 (default, Dec  4 2017, 14:50:18) [GCC 5.4.0 20160609]
```

##### CONFIGURATION
ansible.cfg:
```
[defaults]
inventory      = ./hosts
roles_path     = ./roles
remote_user    = oliver
nocows         = 1
vault_password_file = ./get_vault_password_from_keyring.py

gathering      = smart
fact_caching   = jsonfile
fact_caching_timeout = 21600
fact_caching_connection = ./cache

[privilege_escalation]
become = True
become_method = sudo

[ssh_connection]
pipelining = True
```

##### OS / ENVIRONMENT
Running Ansible on Ubuntu 16.04.4 x86_64; target is the same machine.

Tried with and without python-magic module installed, but didn't observe any different behaviour.

##### SUMMARY
<!--- Explain the problem briefly -->
Documentation for stat module (http://docs.ansible.com/ansible/latest/stat_module.html) mentions that a "mime_type" entry will be set if get_mime is set to true, with example content being "PDF document, version 1.2". I couldn't get this result; rather:
- a "mimetype" entry is set (ie. no underscore)
- the mimetype entry contains the actual mime type (eg. "application/pdf") rather than a description (eg. "PDF document, version 1.2")

##### STEPS TO REPRODUCE
```yaml
- name: Get mime type of test file
  stat: path="/home/oliver/mozilla.pdf"
  register: my_stat_check

- debug:
    msg: "{{ my_stat_check.stat.mimetype }}"

- debug:
    msg: "{{ my_stat_check.stat.mime_type }}"
```


##### EXPECTED RESULTS
I expected the first debug message to fail, and expected the second one to succeed and print "PDF document, version 1.2".

Alternatively, the documentation should state that "mimetype" will be set, and will contain the technical mime type rather than a description.
Though admittedly I'd prefer to also get the descriptive type output, since eg. for swap files the mime type is always "application/octet-stream" (so a swap file is indistinguishable from any other binary file); while the descriptive type is something like "Linux/i386 swap file (new style)" which is more useful.

##### ACTUAL RESULTS
At the moment, the first debug message will work and will print "application/pdf". The second debug message will fail with "The task includes an option with an undefined variable. The error was: 'dict object' has no attribute 'mime_type'".

```
TASK [tools : Get mime type of test file] *****************************************************************************************************************************************************************************************************
ok: [myhost] => {"changed": false, "stat": {"atime": 1519571973.3959274, "attr_flags": "e", "attributes": ["extents"], "block_size": 4096, "blocks": 352, "charset": "binary", "checksum": "2d9eb9f17601726c56bd0c4fbc770430d0ac2277", "ctime": 1519484291.234419, "dev": 2098, "device_type": 0, "executable": false, "exists": true, "gid": 1000, "gr_name": "oliver", "inode": 12592144, "isblk": false, "ischr": false, "isdir": false, "isfifo": false, "isgid": false, "islnk": false, "isreg": true, "issock": false, "isuid": false, "md5": "760bf09b20afc699ad5cb4cabf3a151a", "mimetype": "application/pdf", "mode": "0664", "mtime": 1519484291.234419, "nlink": 1, "path": "/home/oliver/mozilla.pdf", "pw_name": "oliver", "readable": true, "rgrp": true, "roth": true, "rusr": true, "size": 180168, "uid": 1000, "version": "18446744071694658390", "wgrp": true, "woth": false, "writeable": true, "wusr": true, "xgrp": false, "xoth": false, "xusr": false}}

TASK [tools : debug] **************************************************************************************************************************************************************************************************************************
ok: [myhost] => {
    "msg": "application/pdf"
}

TASK [tools : debug] **************************************************************************************************************************************************************************************************************************
fatal: [myhost]: FAILED! => {"msg": "The task includes an option with an undefined variable. The error was: 'dict object' has no attribute 'mime_type'\n\nThe error appears to have been in '/home/oliver/devel/myhost/ansible/roles/tools/tasks/main.yml': line 40, column 3, but may\nbe elsewhere in the file depending on the exact syntax problem.\n\nThe offending line appears to be:\n\n\n- debug:\n  ^ here\n\nexception type: <class 'ansible.errors.AnsibleUndefinedVariable'>\nexception: 'dict object' has no attribute 'mime_type'"}
	to retry, use: --limit @/home/oliver/devel/myhost/ansible/playbooks/desktop.retry
```



Discussion:
Files identified in the description:
* [lib/ansible/modules/files/stat.py](https://github.com/ansible/ansible/blob/devel/lib/ansible/modules/files/stat.py)

If these files are inaccurate, please update the `component name` section of the description or use the `!component` bot command.

[click here for bot help](https://github.com/ansible/ansibullbot/blob/master/ISSUE_HELP.md)
<!--- boilerplate: components_banner --->
cc @bpennypacker
[click here for bot help](https://github.com/ansible/ansibullbot/blob/master/ISSUE_HELP.md)
<!--- boilerplate: notify --->

Resolving patch:
diff --git a/lib/ansible/modules/files/stat.py b/lib/ansible/modules/files/stat.py
--- a/lib/ansible/modules/files/stat.py
+++ b/lib/ansible/modules/files/stat.py
@@ -315,13 +315,13 @@
             returned: success, path exists and user can read stats and installed python supports it
             type: string
             sample: www-data
-        mime_type:
+        mimetype:
             description: file magic data or mime-type
             returned: success, path exists and user can read stats and
                 installed python supports it and the `mime` option was true, will
                 return 'unknown' on error.
             type: string
-            sample: PDF document, version 1.2
+            sample: application/pdf; charset=binary
         charset:
             description: file character set or encoding
             returned: success, path exists and user can read stats and


Test patch: