osx_say: add espeak support, rename module to say (#33071)

* Rename osx_say module into say

* say: remove undocumented default value for voice parameter

* say: add support for espeak command

* say: handle check_mode

* say: handle GNUstep tool

CHANGELOG.md

@@ -35,6 +35,7 @@ Ansible Changes By Release
   in the `md5` return value not being returned. This option will be removed altogether in Ansible
   2.9. use `get_checksum: True` with `checksum_algorithm: md5` to return an md5 hash of the file
   under the `checksum` return value.
+* `osx_say` module was renamed into `say`.
 
 #### Deprecated Modules (to be removed in 2.9):
 * ec2_ami_find: replaced by ec2_ami_facts

docs/docsite/rst/porting_guide_2.5.rst

@@ -89,6 +89,8 @@ This option will be removed starting with Ansible version 2.9. The options ``get
 and ``checksum_algorithm: md5`` can still be used if an MD5 checksum is
 desired.
 
+* ``osx_say`` module was renamed into :ref:`say <say>`.
+
 Plugins
 =======
 

lib/ansible/modules/notification/_osx_say.py

@@ -0,0 +1 @@
+say.py

lib/ansible/modules/notification/osx_say.py

@@ -1,80 +0,0 @@
-#!/usr/bin/python
-# -*- coding: utf-8 -*-
-
-# (c) 2013, Michael DeHaan <michael@ansible.com>
-# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-
-from __future__ import absolute_import, division, print_function
-__metaclass__ = type
-
-
-ANSIBLE_METADATA = {'metadata_version': '1.1',
-                    'status': ['stableinterface'],
-                    'supported_by': 'community'}
-
-
-DOCUMENTATION = '''
----
-module: osx_say
-version_added: "1.2"
-short_description: Makes an OSX computer to speak.
-description:
-   - makes an OS computer speak!  Amuse your friends, annoy your coworkers!
-notes:
-   - If you like this module, you may also be interested in the osx_say callback in the plugins/ directory of the source checkout.
-options:
-  msg:
-    description:
-      What to say
-    required: true
-  voice:
-    description:
-      What voice to use
-    required: false
-requirements: [ say ]
-author:
-    - "Ansible Core Team"
-    - "Michael DeHaan (@mpdehaan)"
-'''
-
-EXAMPLES = '''
-- osx_say:
-    msg: '{{ inventory_hostname }} is all done'
-    voice: Zarvox
-  delegate_to: localhost
-'''
-import os
-
-from ansible.module_utils.basic import AnsibleModule
-
-
-DEFAULT_VOICE = 'Alex'
-
-
-def say(module, msg, voice):
-    module.run_command(["/usr/bin/say", msg, "--voice=%s" % (voice)], check_rc=True)
-
-
-def main():
-
-    module = AnsibleModule(
-        argument_spec=dict(
-            msg=dict(required=True),
-            voice=dict(required=False, default=DEFAULT_VOICE),
-        ),
-        supports_check_mode=False
-    )
-
-    if not os.path.exists("/usr/bin/say"):
-        module.fail_json(msg="/usr/bin/say is not installed")
-
-    msg = module.params['msg']
-    voice = module.params['voice']
-
-    say(module, msg, voice)
-
-    module.exit_json(msg=msg, changed=False)
-
-
-if __name__ == '__main__':
-    main()

lib/ansible/modules/notification/say.py

@@ -0,0 +1,92 @@
+#!/usr/bin/python
+# -*- coding: utf-8 -*-
+
+# (c) 2013, Michael DeHaan <michael@ansible.com>
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+from __future__ import absolute_import, division, print_function
+__metaclass__ = type
+
+
+ANSIBLE_METADATA = {'metadata_version': '1.1',
+                    'status': ['stableinterface'],
+                    'supported_by': 'community'}
+
+
+DOCUMENTATION = '''
+---
+module: say
+version_added: "1.2"
+short_description: Makes a computer to speak.
+description:
+   - makes a computer speak! Amuse your friends, annoy your coworkers!
+notes:
+   - In 2.5, this module has been renamed from M(osx_say) into M(say).
+   - If you like this module, you may also be interested in the osx_say callback plugin.
+options:
+  msg:
+    description:
+      What to say
+    required: true
+  voice:
+    description:
+      What voice to use
+    required: false
+requirements: [ say or espeak ]
+author:
+    - "Ansible Core Team"
+    - "Michael DeHaan (@mpdehaan)"
+'''
+
+EXAMPLES = '''
+- say:
+    msg: '{{ inventory_hostname }} is all done'
+    voice: Zarvox
+  delegate_to: localhost
+'''
+import os
+
+from ansible.module_utils.basic import AnsibleModule, get_platform
+
+
+def say(module, executable, msg, voice):
+    cmd = [executable, msg]
+    if voice:
+        cmd.extend(('-v', voice))
+    module.run_command(cmd, check_rc=True)
+
+
+def main():
+
+    module = AnsibleModule(
+        argument_spec=dict(
+            msg=dict(required=True),
+            voice=dict(required=False),
+        ),
+        supports_check_mode=True
+    )
+
+    msg = module.params['msg']
+    voice = module.params['voice']
+
+    executable = module.get_bin_path('say')
+    if not executable:
+        executable = module.get_bin_path('espeak')
+    elif get_platform() != 'Darwin':
+        # 'say' binary available, it might be GNUstep tool which doesn't support 'voice' parameter
+        voice = None
+        module.warn("'say' executable found but system is '%s': ignoring voice parameter" % get_platform())
+
+    if not executable:
+        module.fail_json(msg="Unable to find either 'say' or 'espeak' executable")
+
+    if module.check_mode:
+        module.exit_json(msg=msg, changed=False)
+
+    say(module, executable, msg, voice)
+
+    module.exit_json(msg=msg, changed=True)
+
+
+if __name__ == '__main__':
+    main()