PyPushover client docs

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 pypushover 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 pypushover 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](https://pushover.net/api/client#download).

>>> 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](https://pushover.net/api/client#p2). 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 interrupted using the stop_listening method.

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

class client.ClientManager(app_token, secret=None, device_id=None)

Manages the interface between the Pushover Servers and user. This can be instantiated with or without the user secret and device id. If no secret is provided, the user MUST login before interfacing with the Pushover servers. If no device id is provided, the user MUST register this client as a device before interfacing with the Pushover servers.

acknowledge_message(receipt)

Sends an acknowledgement to the server that the message was read.

Parameters:receipt – receipt of the message to ack

clear_server_messages()

Clears the messages stored on Pushover servers.

listen(on_msg_receipt)

Listens for messages from the server. When a message is received, a call to the on_msg_receipt function with a

single parameter representing the messages received.

Parameters:on_msg_receipt – function to call when a message is received

listen_async(on_msg_receipt)

Creates a Process for listening to the Pushover server for new messages. This process then listens for messages

from the server. When a message is received, a call to the on_msg_receipt function with a single parameter representing the messages received.

Parameters:on_msg_receipt – function to call when a message is received

login(email, password)

Logs into the Pushover server with the user’s email and password. Retrieves a secret key, stores it, and then returns it.

Parameters:

• email – the users email
• password – the users password

Returns:

register_device(name)

Registers the device (this client) with the name of name. The devices id is then stored and returned.

Parameters:name (str) – Name of the device to register Return string:device_id of the device registered

retrieve_message()

Retrieves messages stored on the Pushover servers and saves them into the messages property.

stop_listening()

Stops the listening process from accepting any more messages.