py-pushover-open-client 1.3.0

Unofficial Python Bindings for PushOver Open Client API

Python Pushover Open Client

py-pushover-open-client aims to provide unofficial Python bindings for Pushover's Open Client API.

Usage

Setup

pip3 install py-pushover-open-client 

Or simply clone this repository, change into it's root directory and run "pip3 install ."

How to Use

You can now import the main client using:

from pushover_open_client import Client

Please see the examples provided for more detail.

Device Registration

The first step is to register a new desktop device with the Pushover servers. This gives us certain device properties, specifically a secret, user key and device key, which can be saved and used by our client to recieve messages.

To do this, you must setup a configuration file in JSON format containing your Pushover's email and password as below:

{
	"email": "[e-mail]",
	"password": "myPushoverPassword",
	"secret": "",
	"deviceID": "",
	"userID": ""
}

Then run code that looks like below. Replace "deviceName" with a device name between 0 and 25 characters long, "yourInConfig.cfg" with the name of your input configuration file, and "yourOutConfig.cfg" with the name intended for your output configuration file.
Note: These can be the same name if you wish.

from pushover_open_client import Client

client = Client("yourInConfig.cfg")
client.login()
client.registerDevice("deviceName")
client.writeConfig("yourOutConfig.cfg")

Assuming the deviceName has not already been taken, your new device will be registered!

Note: If you receive an error message saying you could not register the device, try changing the name to be a unique name.

Receiving Messages

Once you have completed registration of the device, you want to continue to use the output configuration file which was written during registration. This will contain the information needed to log in to the servers and to receive messages.

When you initially start a client, you will want to flush out any previously recorded messages. This is also a good way to test that your registration has been successful, as you will receive at least one test message from Pushover.

To do this, start a new session using the written configuration and get any outstanding messages as below:

client = Client("yourOutConfig.cfg")
messageList = client.getOustandingMessages()

#Process/do work with messageList
if(messageList):
	for m in messageList:
		print m.message

	client.deleteMessages(messageList[-1].id)

After you have flushed out any previous messages, you can connect to the websocket to receive real time messages! This can be done in one of two methods - via polling, or via passing in a callback function (recommended). Here are examples of both:

Polling:

while(True):
	messageList = client.getWebSocketMessages()

	#Prcoess/do work with messageList!
	if(messageList):
		for message in messageList:

			#Do work with message here!

			#Make sure to acknowledge messages with priority >= 2
			if(message.priority >= 2):
				client.acknowledgeEmergency(message.receipt)			

		#Make sure you delete messages that you recieve!
		client.deleteMessages(messageList[-1].id)

	sleep(5) #Wait a few seconds between requests

Callback:

def messageCallback(messageList):
	#Prcoess/do work with messageList!
	if(messageList):
		for message in messageList:

			#Do work with message here!

			#Make sure to acknowledge messages with priority >= 2
			if(message.priority >= 2):
				client.acknowledgeEmergency(message.receipt)			

		#Make sure you delete messages that you recieve!
		client.deleteMessages(messageList[-1].id)

client.getWebSocketMessages(messageCallback)	

And that's it! Please remember to be responsible when accessing Pushover's API!

Message Object

Please see the open client documentation for information regarding what each message contains. Conditional elements are set to None if they do not exist to prevent exceptions.

All Messages Include:
id, umid, title, message, app, aid, icon, date, priority

Some Messages Conditionally Include: 
sound, url, url_title, acked, receipt, html

Acknowledgments

Thanks to the developers of:

• websocket-client
• requests

This client is not written or supported by Superblock, the creators of Pushover.