Apprise: Universal Push Notifications

Warnings

• breaking Version 1.9.4 introduced a major code refactor for Python 3.9+ compatibility. While efforts were made to maintain backward compatibility, users running older Python versions (pre-3.9) might experience unexpected behavior or require adjustments to their code.
  Fix: Ensure your environment uses Python 3.9 or newer. Review your code for any reliance on internal APIs or behaviors that might have changed during the refactor.
• gotcha Many notification services have specific optional dependencies that are not installed by default with `pip install apprise`. Forgetting to install these can lead to runtime `ImportError` exceptions when trying to use certain services.
  Fix: Install Apprise with the specific extras needed for your services (e.g., `pip install 'apprise[slack,telegram]'`) or install all optional dependencies with `pip install 'apprise[all]'`.
• gotcha Notification service URLs are critical for Apprise functionality. Incorrectly formatted URLs, missing authentication tokens, or invalid endpoints are common sources of errors that can prevent notifications from being sent.
  Fix: Always refer to the official Apprise documentation (AppriseIt.com) for the correct URL syntax and required parameters for each service. Utilize environment variables or a secure configuration management system for sensitive credentials.
• gotcha The `Apprise` object is designed to be initialized once and reused throughout your application's lifecycle. Repeatedly creating new `Apprise` instances (e.g., inside a loop or for every notification) can lead to unnecessary overhead and inefficient resource usage.
  Fix: Initialize `Apprise` once, typically at application startup, and reuse the `apobj` instance for all subsequent notifications. Call `apobj.add()` for each unique service URL.

Install

• pip install apprise Base installation
• pip install 'apprise[all]' With all optional dependencies for all services

Imports

• Apprise

  from apprise import Apprise

  While 'import apprise' works, importing Apprise directly is idiomatic and clearer.
• AppriseAsset

  from apprise import AppriseAsset

Quickstart

This quickstart demonstrates how to initialize Apprise, add a notification service URL, and send a basic notification. It also shows how to include a dummy URL for testing output to stdout. For real services, replace `APPRISE_SLACK_URL` with your actual service URL, retrieved from environment variables for security. Remember to install extra dependencies if your chosen service requires them.

import apprise
import os

# Create an Apprise instance
apobj = apprise.Apprise()

# Add a service URL.
# Use a real service URL or a dummy one like 'pypi://' for stdout output.
# Example for Slack: 'slack://tokenA/tokenB/tokenC'
# Example for Telegram: 'tgram://bottoken/chatid'
# Replace with your actual URL. Using os.environ.get for security.
slack_url = os.environ.get('APPRISE_SLACK_URL', 'pypi://')
apobj.add(slack_url)

# Send a notification
apobj.notify(
    body='Hello from Apprise!',
    title='Apprise Quickstart',
    notify_type='info' # info, success, warning, failure
)

print(f"Notification sent (or printed to stdout if using pypi://): {slack_url}")

# Example with a file attachment (requires AppriseAsset and a valid service)
# from apprise import AppriseAsset
# try:
#    with open('example.txt', 'w') as f:
#        f.write('This is an example attachment.')
#    apobj.add('mailto://user@example.com') # Example service supporting attachments
#    apobj.notify(
#        body='Message with an attachment.',
#        attach=AppriseAsset('example.txt')
#    )
# except IOError: # mailto will silently fail without a server
#    print("Could not create example.txt or send attachment.")