Specify device for Pushover notification (#802)

* Specify device for Pushover notification

New parameter: device

Example:
- community.general.pushover:
    msg: '{{ inventory_hostname }} has been lost somewhere'
    app_token: wxfdksl
    user_key: baa5fe97f2c5ab3ca8f0bb59
    device: admins-iPhone
  delegate_to: localhost

Using the Pushover API, you can specify a device where the message should be delivered to. Instead of notifying all devices (the default), the message is sent only to the specified device. Multiple devices can be given separated by a comma.

This change is downwards compatible: omitting the device key sends the message to all devices (as before).

* Added changelog fragments file for pushover

File format as specified in https://docs.ansible.com/ansible/devel/community/development_process.html#changelogs-how-to.

* Added version_added information

As suggested by Felix (thanks!).

Co-authored-by: Felix Fontein <felix@fontein.de>

Co-authored-by: Felix Fontein <felix@fontein.de>

changelogs/fragments/802-pushover-device-parameter.yml

@@ -0,0 +1,2 @@
+minor_changes:
+  - pushover - add device parameter (https://github.com/ansible-collections/community.general/pull/802).

plugins/modules/notification/pushover.py

@@ -1,6 +1,7 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
 # Copyright (c) 2012, Jim Richardson <weaselkeeper@gmail.com>
+# Copyright (c) 2019, Bernd Arnold <wopfel@gmail.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
@@ -38,8 +39,15 @@ options:
     description:
       - Message priority (see U(https://pushover.net) for details).
     required: false
+  device:
+    description:
+      - A device the message should be sent to. Multiple devices can be specified, separated by a comma.
+    required: false
+    version_added: 1.2.0
 
-author: "Jim Richardson (@weaselkeeper)"
+author:
+  - "Jim Richardson (@weaselkeeper)"
+  - "Bernd Arnold (@wopfel)"
 '''
 
 EXAMPLES = '''
@@ -58,6 +66,14 @@ EXAMPLES = '''
     app_token: wxfdksl
     user_key: baa5fe97f2c5ab3ca8f0bb59
   delegate_to: localhost
+
+- name: Send notifications via pushover.net to a specific device
+  community.general.pushover:
+    msg: '{{ inventory_hostname }} has been lost somewhere'
+    app_token: wxfdksl
+    user_key: baa5fe97f2c5ab3ca8f0bb59
+    device: admins-iPhone
+  delegate_to: localhost
 '''
 
 from ansible.module_utils.basic import AnsibleModule
@@ -74,7 +90,7 @@ class Pushover(object):
         self.user = user
         self.token = token
 
-    def run(self, priority, msg, title):
+    def run(self, priority, msg, title, device):
         ''' Do, whatever it is, we do. '''
 
         url = '%s/1/messages.json' % (self.base_uri)
@@ -89,6 +105,10 @@ class Pushover(object):
             options = dict(options,
                            title=title)
 
+        if device is not None:
+            options = dict(options,
+                           device=device)
+
         data = urlencode(options)
 
         headers = {"Content-type": "application/x-www-form-urlencoded"}
@@ -108,12 +128,13 @@ def main():
             app_token=dict(required=True, no_log=True),
             user_key=dict(required=True, no_log=True),
             pri=dict(required=False, default='0', choices=['-2', '-1', '0', '1', '2']),
+            device=dict(type='str'),
         ),
     )
 
     msg_object = Pushover(module, module.params['user_key'], module.params['app_token'])
     try:
-        response = msg_object.run(module.params['pri'], module.params['msg'], module.params['title'])
+        response = msg_object.run(module.params['pri'], module.params['msg'], module.params['title'], module.params['device'])
     except Exception:
         module.fail_json(msg='Unable to send msg via pushover')