client

============================================ client - Client Manager for the Pushover API

This module defines classes and functions necessary to act as a Client to the Pushover servers. For more details about the Pushover API for clients visit their site

Creating a client:

For the first time, creating a client requires the following steps:

1. Create an object of class type ClientManager and pass in your app token
2. Have the user login to the Pushover service with their email and password
3. Register your client service as a new device

While doing these steps, you'll receive a 'secret' and 'device_id'. These are return with the ClientManager.login and ClientManager.register_device methods. They are also stored in the secret and device_id properties. This secret and device id MUST be stored in a safe location if stored at all.

Here is an example:

>>> import py_pushover as py_po
>>> cm = py_po.client.ClientManager('<app token>')
>>> secret = cm.login('user email', 'user pass')
>>> device_id = cm.register_device('device_name')

If you already have a secret and device id, then you can pass those into the ClientManager upon creation:

>>> import py_pushover as py_po
>>> cm = py_po.client.ClientManager('<app token>', secret='<user secret>', device_id='<device id>')

Retrieving Messages:

Messages are retrieved from the Pushover Server by using the retrieve_message method. Once called, all messages stored on the Pushover servers are then stored into the messages property. These messages are a list of dictionaries with items as defined in the Pushover API.

>>> cm.retrieve_message()
>>> for msg in cm.messages:
...     print(msg['message'])

Clearing Messages from Pushover Server:

Messages stored on the Pushover Server should be cleared after being presented to the user. This is done using the clear_server_messages method. Note: This only clears out the messages on Pushover's servers and not the local copy stored in the objects messages property.

>>> cm.clear_server_messages()

Acknowledge an Emergency Message:

If an emergency priority message is received, the Pushover Server should be acknowledged of that receipt per their API guidelines. Once the user has acknowledged the message, using the acknowledge_message method passing in the emergency messages receipt.

>>> cm.retrieve_message()
>>> for msg in cm.messages:
...     print(msg['message'])
...     if msg['priority'] == py_po.PRIORITIES.EMERGENCY:
...         cm.acknowledge_message(msg['receipt'])

Listening Servers:

You can call the listen or listen_async method to constantly listen and respond to messages. Pass in a function to these methods that accepts a single input for the received message(s).

Using the listen method is a Blocking method that will continually run until interrupted either manually (Ctrl+c) or through and unrecoverable loss in connection to the Pushover Servers.

>>> def print_msg(messages):
...     for msg in messages:
...         print(msg['message'])
>>> cm.listen(print_msg)

Using the listen_async method is a non-blocking method that will continually run until interupted using the stop_listening method.

>>> cm.listen_async(print_msg)
>>> time.sleep(30)
>>> cm.stop_listening