py-pushover

A simple Python package for sending Pushover notifications.

Installation

# From GitHub
pip install git+https://github.com/matthewgson/py-pushover.git

# For development
git clone https://github.com/matthewgson/py-pushover.git
cd py-pushover
pip install -e .

Setup

1. Get your Pushover credentials:

   • Sign up and get your user key from the dashboard
   • Register an app to get your API token

2. Option A: Create ~/.pushover config file:

[DEFAULT]
user = your_user_key_here
token = your_app_token_here

3. Option B: Use credentials directly in code:

client = PushoverClient(user="your_user_key", token="your_app_token")

Usage

from pypushover import PushoverClient

# Option 1: Initialize client (reads from ~/.pushover)
client = PushoverClient()

# Option 2: Initialize with credentials directly
client = PushoverClient(user="your_user_key", token="your_app_token")

# Send a simple message
client.send_message("Hello from py-pushover!")

# Send with title
client.send_message("Task completed!", title="Server Alert")

# Message priorities: -2 (silent), -1 (quiet), 0 (normal), 1 (high), 2 (emergency)
client.send_message("Important alert!", priority=1)

# With custom sound
client.send_message("Backup finished", sound="cashregister")

# Emergency priority (requires acknowledgment)
client.send_message(
    "CRITICAL: Server down!", 
    priority=2, 
    retry=30,    # retry every 30 seconds
    expire=3600  # stop after 1 hour
)

Configuration Options

The send_message() method supports all Pushover API parameters:

• message (required) - Your message text
• title - Message title
• priority - Message priority (-2 to 2)
• sound - Notification sound name
• device - Target specific device
• url - Supplementary URL
• url_title - URL button title
• html - Enable HTML formatting
• timestamp - Custom message time
• ttl - Time to live (auto-delete)

Error Handling

from pypushover import PushoverClient, PushoverError

try:
    client = PushoverClient()
    client.send_message("Test message")
except PushoverError as e:
    print(f"Error: {e}")

License

MIT License - see LICENSE file.