notifiers

library1.3.6pypypi✓ verified 85d ago

Notifiers is a Python library that provides a unified and simple interface for sending notifications through various providers like Pushover, Slack, Email, and Telegram. It aims to simplify the process of integrating notifications into applications and scripts without needing to implement individual provider APIs. The current version is 1.3.6, with releases occurring periodically, focusing on new provider additions, bug fixes, and maintenance.

communication

pip install notifiers

github ↗package ↗docs ↗

INSTALL

IMPORT

SIG · NOTIFIERS

notifiers

communicationpythonv1.3.6

Install

3.2s avg

Import

824ms

Disk

25MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.3.6 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 0.865s · 26.6MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 3.2s · import 0.783s · 27MB

25MB installed

● package 25MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

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

✗ from notifiers.pushover import Pushover

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

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.")

Debug

Known issues

breakingThe 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.

affects: >=1.3.0

breakingVersion 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.

affects: >=0.6.4

gotchaNotifiers 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.

affects: All versions

gotchaBy 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.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'notifiers'

The 'notifiers' Python package has not been installed in the active Python environment.

fix

Install the library using pip: `pip install notifiers`

notifiers.exceptions.BadArguments: <NotificationError: Error with sent data: 'message' is a required property>

The notification provider's 'notify()' method was called without one or more of its mandatory arguments (e.g., 'message', 'token', or 'user').

fix

Check the `notifier.required` property for the specific provider to see which arguments are needed, and then provide them in the `notify()` call. Example: `pushover.notify(user='your_user_key', token='your_app_token', message='Hello from Notifiers!')`

notifiers.exceptions.NoSuchNotifierError: Notifier 'nonexistent_provider' does not exist

An attempt was made to instantiate or use a notification provider with a name that is not recognized or supported by the 'notifiers' library.

fix

Verify the provider name against the list of supported providers. You can get a list of available providers using `notifiers.get_notifier.providers()`. Correct the provider name in your code, for example: `from notifiers import get_notifier; p = get_notifier('pushover')`

Upgrade

Version history

1.3.6latest on PyPI · released May 17, 2025

Audit

Dependencies

requestsrequiredUsed for making HTTP requests to notification provider APIs.

jsonschemarequiredUsed for validating notification data against provider-specific schemas.

clickrequiredUsed for the command-line interface (CLI) functionality.

importlib_metadatarequiredAdded in v1.3.6, likely for improved metadata introspection. [cite: 0.6.4 release notes]

Agent activity

14 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/liiight/notifiers ↗

packagehttps://pypi.org/project/notifiers/ ↗

docshttps://notifiers.readthedocs.io/en/latest/ ↗