Apprise Notification Library and CLI

Apprise is a unified notification library designed to send notifications to a wide variety of services (e.g., Telegram, Discord, Slack, Amazon SNS, Gotify) using a single, common, and intuitive syntax.

Key features include:

• Unified Syntax: One library to manage multiple notification services.
• Attachment Support: Handles images and attachments (service-dependent).
• Asynchronous Performance: Messages are sent asynchronously for high performance.
• Lightweight: Minimal footprint.
• Dual Use Cases:
  • Developers: Integrate a single library to gain access to many notification providers.
  • System Administrators/DevOps: Use the included apprise Command Line Interface (CLI) to send notifications from scripts or terminal environments.

When contributing new functionality:

1. Template: Use apprise/plugins/demo.py as a template for new plugins.
2. Testing: Write unit tests in the tests/ directory using the AppriseURLTester pattern.
3. Requirements: All new plugins must include test coverage and pass linting to be accepted.

Apprise supports a vast array of notification services categorized into several types. For a complete and up-to-date list of all supported modules, visit the Official Documentation.

Supported categories include:

• Productivity Based Notifications
• SMS Notifications
• Desktop Notifications
• Email Notifications
• Custom Notifications

When adding a notification service via .add(), you can assign a tag to it. This allows you to selectively target specific groups of services during a .notify() call.

• To notify only services with a specific tag: use tag='your_tag' in .notify().
• To notify absolutely everything (including untagged services): use the reserved tag tag='all' in .notify().

# Add a service with a specific tag
apobj.add('mailto://myuser:mypass@hotmail.com', tag='admin')

# Notify only the 'admin' group
apobj.notify(body='admin message', title='Attention Admins', tag='admin')

# Notify everything regardless of tags
apobj.notify(body='broadcast', title='Hello All', tag='all')

Persistent storage allows Apprise to cache recurring actions to disk to reduce overhead.

Operational States

1. PersistentStoreMode.MEMORY: (Default for API) Disables writing to disk. All caching happens in memory.
2. PersistentStoreMode.AUTO: Writes to disk on demand. (Default for CLI).
3. PersistentStoreMode.FLUSH: Writes to disk during every transaction.

API Configuration

To enable persistent storage in the API, you must provide a storage_path in the AppriseAsset object. You can also configure the storage_mode and the length of the storage_idlen (default is 8).

from apprise import Apprise, AppriseAsset, PersistentStoreMode

# Enable persistent storage with specific settings
asset = AppriseAsset(
    storage_path="/path/to/save/data",
    storage_mode=PersistentStoreMode.FLUSH,
    storage_idlen=8
)

aobj = Apprise(asset=asset)

SMS notifications in Apprise typically consist of a single body (usually limited to 160 characters). Because most SMS services do not support separate title and body fields, Apprise automatically combines the title and body into a single message before transmission.

Use the specific Service ID and syntax provided for your chosen provider to configure these notifications.

Apprise uses Ruff for linting and formatting, configured via pyproject.toml. You can run these tasks through tox:

• Linting: Checks for code violations.
• Formatting: Automatically fixes formatting where possible.

Note: Linting is enforced on all Pull Requests via GitHub Actions.

# Run linting
tox -e lint

# Fix formatting automatically
tox -e format

Use tox environments to run different levels of testing:

• Full testing and plugin coverage: Use the qa environment.
• Focused testing: Use the -k flag to filter specific tests (e.g., by keyword).
• Minimal testing: Use the minimal environment for a faster, reduced dependency test set.

# Full testing
tox -e qa

# Focused testing (e.g., email-related)
tox -e qa -- -k email

# Minimal dependency test set
tox -e minimal

Instead of providing URLs manually, you can use the --config (-c) option to point to a configuration file (e.g., YAML) or a remote URL containing your notification service definitions. This allows you to manage multiple services centrally.

# Load services from a local YAML file
apprise -vv -t "my title" -b "my notification body" --config=~/apprise.yml

# Load services from a remote configuration URL
apprise -vv -t "my title" -b "my notification body" --config=https://localhost/my/apprise/config

Apprise man pages are generated from Markdown files in the man/*.md directory using Ronn. To regenerate the man page (e.g., man/apprise.1) after updating the source Markdown files, use the tox man target.

# rebuild man page
tox -e man

Apprise uses tox to manage dependencies, linting, testing, and builds. Instead of manually installing requirements, use tox to orchestrate the development lifecycle.

To get started, install tox via pip:

python -m pip install tox