Developer Interface

Main Interface

class chump.Application(token)

The Pushover application in use.

Parameters:token (string) – The application’s API token.

token = None

A string of the application’s API token.

limit = None

If a message has been sent, an int of the application’s monthly message limit, otherwise None.

remaining = None

If a message has been sent, an int of the application’s remaining message allotment, otherwise None.

reset = None

If a message has been sent, datetime of when the application’s monthly message limit will reset, otherwise None.

is_authenticated

A lazily loaded bool indicating whether the application is authenticated.

sounds

A lazily loaded dict of available notification sounds if authenticated, otherwise None.

get_user(token)

Returns a User attached to the Application instance.

Parameters:token (string) – User API token. Return type:A User.

class chump.User(app, token)

A Pushover user. The user is tied to a specific Application, which can be changed later by setting app.

Parameters:

• app (Application) – The Pushover application to send messages with.
• token (string) – The user’s API token.

app = None

The Pushover application to send messages with.

token = None

A string of the user’s API token.

is_authenticated

A lazily loaded bool indicating whether the user is authenticated.

devices

A lazily loaded a set of the user’s devices if authenticated, otherwise None.

create_message(message, html=False, title=None, timestamp=None, url=None, url_title=None, device=None, priority=0, callback=None, retry=30, expire=86400, sound=None)

Creates a message to the User with app.

Parameters:

• message (string) – Body for the message.
• html (bool) – Whether the message should be formatted as HTML. Defaults to False.
• title (string) – (optional) Title for the message. Defaults to None.
• timestamp (datetime or int) – (optional) Date and time to give the message. Defaults to the time the message was created.
• url (string) – (optional) URL to include in the message. Defaults to None.
• device (string) – (optional) device from devices to send to. Defaults to all of the user’s devices.
• priority (int) – (optional) priority for the message. The constants LOWEST, LOW, NORMAL, HIGH, and EMERGENCY may be used for convenience. Defaults to NORMAL.
• callback (string) – (optional) If priority is EMERGENCY, the URL to ping when the message is acknowledged. Defaults to None.
• retry (int) – (optional) If priority is EMERGENCY, the number of seconds to wait between re-alerting the user. Must be greater than 30. Defaults to 30.
• expire (int) – (optional) If priority is EMERGENCY, the number of seconds to retry before giving up on alerting the user. Must be less than 86400. Defaults to 86400.
• sound (string) – (optional) The sound from app.sounds to play when the message is received. Defaults to the user’s default sound.

Returns:

An unsent message.

Return type:

A Message or EmergencyMessage.

send_message(message, html=False, title=None, timestamp=None, url=None, url_title=None, device=None, priority=0, callback=None, retry=30, expire=86400, sound=None)

Does the same as create_message(), but then sends the message with app.

Returns:A sent message. Return type:A Message or EmergencyMessage.

Lower-Level Classes

class chump.Message(user, message, html=False, title=None, timestamp=None, url=None, url_title=None, device=None, priority=0, sound=None)

A Pushover message. The message is tied to a specific Application, and User. All parameters are exposed as attributes on the message, for convenience.

Parameters:user (User) – The user to send the message to.

All other arguments are the same as in User.create_message().

id = None

A string of the id of the message if sent, otherwise None.

is_sent = None

A bool indicating whether the message has been sent.

sent_at = None

A datetime of when the message was sent, otherwise None.

error = None

An APIError if there was an error sending the message, otherwise None.

send()

Sends the message. If called after the message has been sent, resends it.

Returns:A bool indicating if the message was successfully sent. Return type:A bool.

class chump.EmergencyMessage(user, message, html=False, title=None, timestamp=None, url=None, url_title=None, device=None, sound=None, callback=None, retry=30, expire=86400)

Bases: chump.Message

An emergency Pushover message, (that is, a message with the priority of EMERGENCY).

All arguments are the same as in Message, with the additions of callback, retry, and timeout, which are all, too, as defined in User.create_message().

receipt = None

A string of the receipt returned by the endpoint, for polling.

last_polled_at = None

A datetime of when the message was last polled.

last_delivered_at = None

A datetime of when the message was last delivered.

is_acknowledged = None

A bool indicating whether the message has been acknowledged.

acknowledged_at = None

A datetime of when the message was acknowledged, otherwise None.

acknowledged_by = None

A User of the first user to have acknowledged the notification, otherwise None.

is_expired = None

A bool indicating whether the message has expired.

expires_at = None

A datetime of when the message expires.

is_called_back = None

A bool indicating whether the message has been called back.

called_back_at = None

A datetime of when the message was called back, otherwise None.

send()

Sends the message. If called after the message has been sent, resends it.

Returns:A bool indicating if the message was successfully sent. Return type:A bool.

poll()

Polls for the results of the sent message. If the message has not been sent, does so.

Returns:A bool indicating if the message has not expired, called back nor been acknowledged, or None if the message has no receipt with which to poll. Return type:A bool or None.

cancel()

Cancels the request for acknowledgment of a sent message.

Returns:A bool indicating if the message was successfully cancelled. Return type:A bool.

Exceptions

exception chump.APIError(url, request, response, timestamp)

Pushover errors eponysterically end up here.

Parameters:

• url (string) – The URL of the original request.
• request (dict) – The original request payload.
• response (dict) – The json response from the endpoint.
• timestamp (datetime) – When this error was raised.

url = None

A string of the URL of the original request.

request = None

A dict of the original request payload.

response = None

A dict of the json response from the endpoint.

timestamp = None

A datetime of when this error was raised.

id = None

A string of the request’s id.

status = None

An int of the status code.

errors = None

A list of human readable error messages as strings.

bad_inputs = None

A dict of the request’s original arguments that the endpoint didn’t like as strings and why, also as strings.

receipt = None

A string of the message’s receipt if it was an emergency message, otherwise None.

Constants

chump.LOWEST = -2

Message priority: No sound, no vibration, no banner.

chump.LOW = -1

Message priority: No sound, no vibration, banner.

chump.NORMAL = 0

Message priority: Sound, vibration, and banner if outside of user’s quiet hours.

chump.HIGH = 1

Message priority: Sound, vibration, and banner regardless of user’s quiet hours.

chump.EMERGENCY = 2

Message priority: Sound, vibration, and banner regardless of user’s quiet hours, and re-alerts until acknowledged.