Notifiers

Warnings

• breaking The HipChat notification provider was removed in version 1.3.0. Users relying on HipChat must migrate to another provider or downgrade to an earlier version. [cite: 0.6.4 release notes, 1.3.0 release notes]
  Fix: Migrate to a different notification provider supported by Notifiers (e.g., Slack, Telegram) and update your code accordingly. Consider using version <1.3.0 if HipChat support is critical and migration is not feasible.
• breaking Version 0.6.4 introduced a 'Major refactor' of provider resources and a significant overhaul of the CLI. This changed how provider-specific resources (like `telegram.updates()`) are accessed and often introduced new validation requirements (e.g., needing a `token` for resource calls). The CLI syntax also fundamentally changed from `keyword=value` to standard command options. [cite: 13, 0.6.4 release notes]
  Fix: Review the documentation for your specific provider and CLI usage. Ensure all required arguments are passed to resource calls and adapt CLI commands to the new option-based syntax. For Python API, `get_notifier` remains the entry point, but subsequent calls to provider-specific resources might require additional arguments.
• gotcha Notifiers uses JSON Schema for provider validation. If required parameters are missing or invalid, a `notifiers.exceptions.BadArguments` exception will be raised. Each provider has its own schema, which can be inspected via `notifier.schema` or `notifier.required`.
  Fix: Always check the `notifier.required` or `notifier.schema` properties for a given provider to understand the expected arguments and their types. Ensure all mandatory parameters are passed to the `notify` method.
• gotcha By default, the `NotificationResponse` object returned by `notify()` methods does *not* raise an exception on API errors from the notification provider. To explicitly catch errors, you must either call `response.raise_on_errors()` or pass `raise_on_errors=True` to the `notify()` method.
  Fix: For reliable error handling, always use `raise_on_errors=True` in your `notify()` calls or explicitly check `response.ok` and `response.errors` after sending a notification.

Install

• pip install notifiers Install stable version

Imports

• get_notifier

  from notifiers import get_notifier

  This is the primary and recommended way to instantiate a notifier for a specific provider.
• notify

  from notifiers import notify

  Use this function for a quick one-off notification without needing to explicitly get a provider object first.
• Pushover

  from notifiers.providers.pushover import Pushover

  While direct provider imports are possible, they must come from the `notifiers.providers` submodule. Using `get_notifier` is generally easier.

Quickstart

This quickstart demonstrates how to send a notification using the 'pushover' provider. It fetches credentials from environment variables (or placeholders) and uses the `get_notifier` function. It also explicitly sets `raise_on_errors=True` for robust error handling.

import os
from notifiers import get_notifier

pushover_token = os.environ.get('NOTIFIERS_PUSHOVER_TOKEN', 'YOUR_PUSHOVER_API_TOKEN')
pushover_user = os.environ.get('NOTIFIERS_PUSHOVER_USER', 'YOUR_PUSHOVER_USER_KEY')

if pushover_token and pushover_user:
    pushover = get_notifier('pushover')
    try:
        # Ensure required parameters are provided. Check pushover.required or pushover.schema
        # for details. Using raise_on_errors=True for explicit error handling.
        response = pushover.notify(
            token=pushover_token,
            user=pushover_user,
            message='Hello from notifiers!',
            title='Python Notification',
            raise_on_errors=True
        )
        if response.status == 'success':
            print(f"Pushover notification sent successfully: {response.data}")
        else:
            print(f"Pushover notification failed: {response.errors}")
    except Exception as e:
        print(f"An error occurred while sending notification: {e}")
else:
    print("Pushover API token and user key not set. Please set NOTIFIERS_PUSHOVER_TOKEN and NOTIFIERS_PUSHOVER_USER environment variables or hardcode them.")