API Reference

This part of the documentation covers all of the interfaces exposed by pushover_complete.

The PushoverAPI Class

This class is your gateway to interacting with the Pushover API. Each instance is initialized with a Pushover application token and makes API calls on behalf of that application.

Main Interface

The methods represent most of the useful functions of PushoverAPI.

class pushover_complete.PushoverAPI(token)[source]

The object representing an application interacting with the Pushover API.

Instantiated with a Pushover application token. All API calls made via that instance will use the provided application token.

Parameters:: token (str) – A Pushover application token

send_message(user, message, device=None, title=None, url=None, url_title=None, image=None, priority=None, retry=None, expire=None, callback_url=None, timestamp=None, sound=None, html=False, ttl=None)[source]

Send a message via the Pushover API.

Parameters:

user (str) – A Pushover user token representing the user or group to whom the message will be sent
message (str) – The message to be sent
device (str or list) – A string or iterable representing the device(s) to which the message will be sent
title (str) – The title of the message
url (str) – A URL to be included with the message
url_title (str) – The link text to be displayed for the URL. If omitted, the URL itself is displayed.
image (str, pathlib.Path, pathlib2.Path (only in Python 2), or file-like) – The file path pointing to the image to be attached to the message or a file-like object representing the image data.
priority (int) – An integer representing the priority of the message, from -2 (least important) to 2 (emergency). Default is 0.
retry (int) – How often the Pushover server will re-send an emergency-priority message in seconds. Required with priority 2 messages.
expire (int) – How long an emergency-priority message will be re-sent for in seconds
callback_url (str) – A url to be visited by the Pushover servers upon acknowledgement of an emergency-priority message
timestamp (int) – A Unix timestamp of the message’s date and time to be displayed instead of the time the message is received by the Pushover servers
sound (str) – A string representing the sound to be played with the message instead of the user’s default. Available sounds can be retreived using PushoverAPI.get_sounds().
html (int) – An integer representing if HTML formatting will be enabled for the message text. Set to 1 to enable.
ttl (int) – An integer representing Time to Live in seconds, after which the message will be automatically deleted.

Returns:

Response body interpreted as JSON

Return type:

dict

send_messages(messages)[source]

Send multiple messages with one call. Utilizes a single HTTP session to decrease overhead.

Parameters:: messages – An iterable of messages to be sent. Each item in the iterable must be expandable using the **kwargs syntax with the keys matching the parameters of PushoverAPI.send_message().
Returns:: Response body interpreted as JSON
Return type:: list[dict]

get_sounds()[source]

Get the current list of supported sounds from the Pushover servers.

Returns:: A dict of sounds, with keys representing the identifier and values a human-readable name.
Return type:: dict

validate(user, device=None)[source]

Validate a user or group token or a user device.

Parameters:

user (str) – A Pushover user or group token to validate
device (str) – A string representing a device name to validate

Returns:

Response body interpreted as JSON

Return type:

dict

check_receipt(receipt)[source]

Check a receipt issued after sending an emergency-priority message.

Parameters:: receipt (str) – The receipt id
Returns:: Response body interpreted as JSON
Return type:: dict

cancel_receipt(receipt)[source]

Cancel a receipt (and thus further re-sends of the message).

Parameters:: receipt (str) – The id of the receipt id to be cancelled
Returns:: Response body interpreted as JSON
Return type:: dict

migrate_to_subscription(user, subscription_code, device=None, sound=None)[source]

Migrate a user key to a subscription key.

Parameters:

user (str) – The user key to migrate
subscription_code (str) – The subscription code to migrate the user to
device (str) – The user’s device that the subscription will be limited to
sound (str) – The user’s preferred sound

Returns:

Response body interpreted as JSON

Return type:

dict

migrate_multiple_to_subscription(users, subscription_code)[source]

Migrate multiple users to subscriptions with one call. Utilizes a single HTTP session to decrease overhead.

Parameters:

users – An iterable of messages to be sent. Each item in the iterable must be expandable using the **kwargs syntax with keys matching user and, optionally, device and sound. Compare to PushoverAPI.migrate_to_subscription().
subscription_code (str) – The subscription code to migrate the user to

Returns:

Response body interpreted as JSON

Return type:

dict

group_info(group_key)[source]

Retrieve information about a delivery group.

Parameters:: group_key (str) – A Pushover group key
Returns:: Response body interpreted as JSON
Return type:: dict

group_add_user(group_key, user, device=None, memo=None)[source]

Add a user to a group.

Parameters:

group_key (str) – A Pushover group key
user (str) – The user key to be added to the group
device (str) – A string representing the device name to add to the group
memo (str) – A memo to store with the user’s group membership (max 200 characters)

Returns:

Response body interpreted as JSON

Return type:

dict

group_delete_user(group_key, user)[source]

Remove user from a group.

Parameters:

group_key (str) – A Pushover group key
user (str) – The user key to remove from the group

Returns:

Response body interpreted as JSON

Return type:

dict

group_disable_user(group_key, user)[source]

Temporarily disable a user in a group.

Parameters:

group_key (str) – A Pushover group key
user (str) – The user key to disable

Returns:

Response body interpreted as JSON

Return type:

dict

group_enable_user(group_key, user)[source]

Re-enable a user in a group.

Parameters:

group_key (str) – A Pushover group key
user (str) – The user key to enable

Returns:

Response body interpreted as JSON

Return type:

dict

group_rename(group_key, new_name)[source]

Change the name of a group.

Parameters:

group_key (str) – A Pushover group key
new_name (str) – The new name for the group

Returns:

Response body interpreted as JSON

Return type:

dict

assign_license(user_identifier, os=None)[source]

Assign a Pushover license to a user.

Parameters:

user_identifier (str) – A Pushover user key or email identifying the user to assign the license to
os (str) – An OS to limit the license. Available options are Android, iOS, or Desktop

Returns:

Response body interpreted as JSON

Return type:

dict

“Private” Methods

These methods, although “private” and used internally by other PushoverAPI methods could be useful in some circumstances, particularly when many requests are to be made at one time.

class pushover_complete.PushoverAPI[source]

_send_message(user, message, device=None, title=None, url=None, url_title=None, image=None, priority=None, retry=None, expire=None, callback_url=None, timestamp=None, sound=None, html=False, ttl=None, session=None)[source]

Send a message via the Pushover API with control over the HTTP session.

Takes a session parameter to use for sending HTTP requests, allowing the re-use of sessions to decrease overhead. Used to abstract the differences between PushoverAPI.send_message() and PushoverAPI.send_messages(). Feel free to call directly if your use case isn’t fulfilled by the more public methods.

Parameters:

user (str) – A Pushover user token representing the user or group to whom the message will be sent

message (str) – The message to be sent

device (str or list) – A string or iterable representing the device(s) to which the message will be sent

title (str) – The title of the message

url (str) – A URL to be included with the message

url_title (str) – The link text to be displayed for the URL. If omitted, the URL itself is displayed.

image (str, pathlib.Path, pathlib2.Path (only in Python 2), or file-like) – The file path pointing to the image to be attached to the message or a file-like-object representing the image data.

priority (int) – An integer representing the priority of the message, from -2 (least important) to 2 (emergency). Default is 0.

retry (int) – How often the Pushover server will re-send an emergency-priority message in seconds. Required with priority 2 messages.

expire (int) – How long an emergency-priority message will be re-sent for in seconds

callback_url (str) – A url to be visited by the Pushover servers upon acknowledgement of an emergency-priority message

timestamp (int) – A Unix timestamp of the message’s date and time to be displayed instead of the time the message is received by the Pushover servers

sound (str) – A string representing a sound to be played with the message instead of the user’s default

html (int) – An integer representing if HTML formatting will be enabled for the message text. Set to 1 to enable.

ttl (int) – An integer representing Time to Live in seconds, after which the message will be automatically deleted.

session (requests.Session) – A requests.Session object to be used to send HTTP requests. Useful to send multiple messages without opening multiple HTTP sessions.

Returns:

Response body interpreted as JSON

Return type:

dict

_migrate_to_subscription(user, subscription_code, device=None, sound=None, session=None)[source]

Migrates a user key to a subscription key.

Takes a session parameter to use for sending HTTP requests, allowing the re-use of sessions to decrease overhead. Used to abstract the differences between PushoverAPI.migrate_to_subscription() and PushoverAPI.migrate_multiple_to_subscription(). Feel free to call directly if your use case isn’t fulfilled by the more public methods.

Parameters:

user (str) – The user key to migrate

subscription_code (str) – The subscription code to migrate the user to

device (str) – The user’s device that the subscription will be limited to

sound (str) – The user’s preferred sound

session (requests.Session) – A requests.Session object to be used to send HTTP requests. Useful to send multiple messages without opening multiple HTTP sessions.

Returns:

Response body interpreted as JSON

Return type:

dict

_generic_get(endpoint, url_parameter=None, payload=None, session=None)[source]

Make a GET request to the Pushover API.

Parameters:

endpoint (str) – The endpoint of the API to hit. Will be joined with “https://api.pushover.net/1/”. Example value: “groups/{}.json”

url_parameter (str) – A parameter to replace in the endpoint string provided. Example value: “g123456”. Combined with the above example value, would result in a final URL of “https://api.pushover.net/1/groups/g123456.json”

payload (dict) – A dict of parameters to be appended to the URL, e.g. {'test-param': False} would result in the URL having ?test-param=false appended. Do not include the application token in this dict, as it is added by the function.

session (requests.Session) – A requests.Session object to be used to send HTTP requests.

Returns:

Response body interpreted as JSON

Return type:

dict

Raises:

BadAPIRequestError – Raised when the Pushover response body contains a status code other than 1.

_generic_post(endpoint, url_parameter=None, payload=None, session=None, files=None)[source]

Make a POST request to the Pushover API.

Parameters:

endpoint (str) – The endpoint of the API to hit. Will be joined with “https://api.pushover.net/1/”. Example value: “groups/{}.json”.

url_parameter (str) – A parameter to replace in the endpoint string provided. Example value: “g123456”. Combined with the above example value, would result in a final URL of “https://api.pushover.net/1/groups/g123456.json”.

payload (dict) – A dict of parameters to be appended to the URL, e.g. {'test-param': False} would result in the URL having ?test-param=false appended. Do not include the application token in this dict, as it is added by the function.

files (dict{str, file-like} or dict{str, tuple(str, file-like[, str[, dict]])}) – (optional) A dict of 'attachment': value for attachment to the message. value may be a file-like object, or a tuple of at least ('filename', file-like[, 'content_type'[, custom_headers_dict]]). The optional ‘content_type’ string describes the file type and custom_headers_dict is a dict-like-object with additional headers describing the file.

session (requests.Session) – A requests.Session object to be used to send HTTP requests.

Returns:

Response body interpreted as JSON

Return type:

dict

Raises:

BadAPIRequestError – Raised when the Pushover response body contains a status code other than 1.

Exceptions and Errors

exception pushover_complete.PushoverCompleteError[source]

Root exception for pushover_complete exceptions.

Only used to except any pushover_complete error. Will never be raised explicitly.

exception pushover_complete.BadAPIRequestError[source]: An exception raised when Pushover’s API responds to a request with an error.