def assign_license(token, user=None, email=None, os=None):
"""
Args:
token:
user:
email:
os:
Returns:
"""
if not(user) and not(email):
raise ValueError("An email or user_key is required")
params = {
'token':token
}
# if both user key and email are sent, we prefer the user key
if user:
params['user'] = user
else:
params['email'] = email
if os:
params['os'] = os
send(_assign_url, data_out=params)
def cancel_retries(token, receipt):
"""
Ceases retrying to notify the user of an Emergency Priority notification.
Cancel an emergency-priority notification early.
:param str token: application token
:param str receipt: receipt of the message
"""
url_to_send = _cancel_receipt_url.format(receipt=receipt)
return send(url_to_send, data_out={'token': token})
def check_receipt(token, receipt):
"""
Check to see if an Emergency Priority notification has been acknowledged.
:param str token: the application token
:param str receipt: the message receipt
:return:
"""
url_to_send = _receipt_url.format(receipt=receipt)
return send(url_to_send, data_out={'token': token}, get_method=True)
def acknowledge_message(self, receipt):
"""
Sends an acknowledgement to the server that the message was read.
:param receipt: receipt of the message to ack
"""
params = {
'secret': self.__secret__
}
self.latest_response_dict = send(self._ack_message_url.format(receipt_id=receipt), params)
def clear_server_messages(self):
"""
Clears the messages stored on Pushover servers.
"""
if self.messages:
params = {
'secret': self.__secret__,
'message': max([i['id'] for i in self.messages])
}
self.latest_response_dict = send(self._del_message_url.format(device_id=self.__device_id__), params)
def retrieve_message(self):
"""
Retrieves messages stored on the Pushover servers and saves them into the `messages` property.
"""
params = {
'secret': self.__secret__,
'device_id': self.__device_id__
}
self.latest_response_dict = send(self._message_url, data_out=params, get_method=True)
self.messages = self.latest_response_dict['messages']
def info(app_token, group):
"""
Fetches the group name and a list of users subscribed to the group.
:param str app_token: your applications token
:param str group: the group id to return info on
:return: A dictionary representing the json response.
"""
param_data = {
'token': app_token,
}
return send(_group_info_url.format(group_key=group), param_data, get_method=True)
def enable_user(app_token, group, user):
"""
Enables the user to receive notifications sent to the group
:param str app_token: your applications token
:param str group: the group id
:param str user: the user id of the user to enable
:return: A dictionary representing the json response.
"""
param_data = {
'token': app_token,
'user': user
}
return send(_group_ena_user_url.format(group_key=group), param_data)
def rename(app_token, group, name):
"""
Renames the group
:param str app_token: your applications token
:param str group: the group id
:param str name: the name of the group to change to
:return: A dictionary representing the json response.
"""
param_data = {
'token': app_token,
'name': name
}
return send(_group_ren_url.format(group_key=group), param_data)
def remove_user(app_token, group, user):
"""
Removes the selected user from the group
:param str app_token: your applications token
:param str group: the group id
:param str user: the user id of the user to deleted
:return: A dictionary representing the json response.
"""
param_data = {
'token': app_token,
'user': user
}
return send(_group_del_user_url.format(group_key=group), param_data)
def register_device(self, name):
"""
Registers the device (this client) with the name of `name`. The devices id is then stored and returned.
:param str name: Name of the device to register
:return string: device_id of the device registered
"""
params = {
'secret': self.__secret__,
'name': name,
'os': 'O'
}
self.latest_response_dict = send(self._register_device_url, data_out=params)
self.__device_id__ = self.latest_response_dict['id']
return self.__device_id__
def login(self, email, password):
"""
Logs into the Pushover server with the user's email and password. Retrieves a secret key, stores it, and then
returns it.
:param email: the users email
:param password: the users password
:return:
"""
params = {
'email': email,
'password': password
}
self.latest_response_dict = send(self._login_url, data_out=params)
self.__secret__ = self.latest_response_dict['secret']
return self.__secret__
def verify_user(app_token, user, device=None):
"""
Verifies whether a userID is a valid ID if device is given, then the user/device pair is verified.
:param device:
:param app_token: the application token
:param user: the user id
:return :
"""
param_data = {
'token': app_token,
'user': user,
}
if device:
param_data['device'] = device
return send(verify_url, param_data)['status'] == 1 # An HTTPError will be raised if invalid
def add_user(app_token, group, user, device=None, memo=None):
"""
Adds the selected user to the group
:param str app_token: your applications token
:param str group: the group id
:param str user: the user id of the user to add
:param str device: the associated device name (optional)
:param str memo: memo (optional)
:return: A dictionary representing the json response.
"""
param_data = {
'token': app_token,
'user': user
}
if device:
param_data['device'] = device
if memo:
param_data['memo'] = memo
return send(_group_add_user_url.format(group_key=group), param_data)
def push_message(token, user, message, **kwargs):
"""
Send message to selected user/group/device.
:param str token: application token
:param str user: user or group id to send the message to
:param str message: your message
:param str title: your message's title, otherwise your app's name is used
:param str device: your user's device name to send the message directly to that device
:param list device: your user's devices names to send the message directly to that device
:param str url: a supplementary URL to show with your message
:param str url_title: a title for your supplementary URL, otherwise just the URL is shown
:param int priority: message priority (Use the Priority class to select)
:param int retry: how often (in seconds) the Pushover servers will retry the notification to the user (required
only with priority level of Emergency)
:param int expire: how many seconds your notification will continue to be retried (required only with priority
level of Emergency)
:param datetime timestamp: a datetime object repr the timestamp of your message's date and time to display to the user
:param str sound: the name of the sound to override the user's default sound choice (Use the Sounds consts to
select)
:param bool html: Enable rendering message on user device using HTML
"""
data_out = {
'token': token,
'user': user, # can be a user or group key
'message': message
}
# Support for non-required parameters of PushOver
if 'title' in kwargs:
data_out['title'] = kwargs['title']
if 'device' in kwargs:
temp = kwargs['device']
if type(temp) == list:
data_out['device'] = ','.join(temp)
else:
data_out['device'] = temp
data_out['device'] = kwargs['device']
if 'url' in kwargs:
data_out['url'] = kwargs['url']
if 'url_title' in kwargs:
data_out['url_title'] = kwargs['url_title']
if 'priority' in kwargs:
data_out['priority'] = kwargs['priority']
# Emergency prioritized messages require 'retry' and 'expire' to be defined
if data_out['priority'] == PRIORITIES.EMERGENCY:
if 'retry' not in kwargs:
raise TypeError('Missing `retry` argument required for message priority of Emergency')
else:
retry_val = kwargs['retry']
# 'retry' val must be a minimum of _MIN_RETRY and max of _MAX_EXPIRE
if not (_MIN_RETRY <= retry_val <= _MAX_EXPIRE):
raise ValueError('`retry` argument must be at a minimum of {} and a maximum of {}'.format(
_MIN_RETRY, _MAX_EXPIRE
))
data_out['retry'] = retry_val
if 'expire' not in kwargs:
raise TypeError('Missing `expire` arguemnt required for message priority of Emergency')
else:
expire_val = kwargs['expire']
# 'expire' val must be a minimum of _MIN_RETRY and max of _MAX_EXPIRE
if not(_MIN_RETRY <= expire_val <= _MAX_EXPIRE):
raise ValueError('`expire` argument must be at a minimum of {} and a maximum of {}'.format(
_MIN_RETRY, _MAX_EXPIRE
))
data_out['expire'] = expire_val
# Optionally a callback url may be supplied for the Emergency Message
if 'callback' in kwargs:
data_out['callback'] = kwargs['callback']
if 'timestamp' in kwargs:
data_out['timestamp'] = int(time.mktime(kwargs['timestamp'].timetuple()))
if 'sound' in kwargs:
data_out['sound'] = kwargs['sound']
if 'html' in kwargs:
data_out['html'] = int(kwargs['html'])
return send(_push_url, data_out=data_out)
