saltext.pushover.utils.pushover¶

Utility functions for interacting with the Pushover API.

class saltext.pushover.utils.pushover.PushoverAPIError(*args: Any, **kwargs: Any)[source]¶: Generic exception to render Pushover API errors.

saltext.pushover.utils.pushover.query(endpoint, method='POST', *, data=None, query_params=None, token=None, api_version='1', header_dict=None, opts=None)[source]¶

Changed in version 2.0.0: * Parameters have been reordered. * Uses JSON request bodies by default. * Errors result in exceptions. * Returns the decoded response data only.

Query the Pushover API.

endpoint: API endpoint to query (without .json suffix), e.g. messages.

Changed in version 2.0.0: Previously, the first parameter was an internally defined identifier. This accepts all API paths.
method: HTTP method. Defaults to POST.
data: Request body data.

Changed in version 2.0.0: Automatically dumped to JSON, unless the Content-Type header is set explicitly in header_dict.
query_params: URI query parameter dictionary.
token: Pushover API token. Optional if already specified in data or query_params, depending on the method. Overrides them.
api_version: API version. Used for building query URI. Defaults to 1.
header_dict: HTTP request headers to add.
opts: Pass through __opts__ to respect Salt HTTP configuration.

saltext.pushover.utils.pushover.validate_sound(sound, token, *, context=None, opts=None)[source]¶

Validate that a specified sound value exists.

sound: Sound to verify
token: Pushover API token
context: Pass through __context__ to allow caching.

Added in version 2.0.0.
opts: Pass through __opts__ to respect Salt HTTP configuration.

Added in version 2.0.0.

saltext.pushover.utils.pushover.validate_user(user, token, device=None, *, context=None, opts=None)[source]¶

Validate that a user/group ID (key) exists and has at least one active device. If device is not falsy, additionally validate that the device exists in the account.

user: User or group name to validate. Required.
token: Pushover API token. Required.
device: Optional device for user to validate. If unspecified, checks whether any device is available.
context: Pass through __context__ to allow caching.

Added in version 2.0.0.
opts: Pass through __opts__ to respect Salt HTTP configuration.

Added in version 2.0.0.

saltext.pushover.utils.pushover.post_message(message, user, token, *, title=None, device=None, priority=0, expire=None, retry=None, sound=None, opts=None)[source]¶

Added in version 2.0.0.

Send a message to a Pushover user or group.

message: Message text to send. Required.
user: User or group of users to send the message to. Must be a user/group ID (key), not a name or an email address. Required.
token: Pushover API token. Required.
title: Message title. Defaults to Message from Salt.
device: Name of the device to send the message to. Defaults to all devices of the user.
priority: Message priority (integers between -2 and 2). Defaults to 0.

Note

Emergency priority (2) requires expire and retry parameters to be set.
expire: Stop notifying the user after the specified amount of seconds. The message is still shown after expiry.
retry: Repeat the notification after this amount of seconds. Minimum: 30.
sound: Notification sound to play. Defaults to user default.
opts: Pass through __opts__ to respect Salt HTTP configuration.