Warning

This is the documentation for a development version of pushover_complete.

Documentation for the Most Recent Stable Version

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)[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.
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, session=None)[source]¶

The internal function used to send messages via the Pushover API. 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. 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]¶

The internal function to migrate 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]¶

A method for abstracting GET requests 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

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

A method for abstracting POST requests 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

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.