The notifications.py module

Summary

Classes

AnsysNotifier

Desktop and multi-channel notifier for PyAnsys job-completion events.

Enums

NotificationChannel	Well-known apprise notification channel URL schemes.
NotificationFormat	Body format of the notification.
NotificationType	Notification type / type of the notification.

Functions

get_notification_channels	Return the global default notification channels.
get_notification_level	Return the global default notification level.
get_notify_on_failure	Return the global default for whether failure notifications are sent.
get_failure_notification_level	Return the global default notification level used on failure.
set_notification_channels	Set the global default notification channels.
set_notification_level	Set the global default notification level.
set_notify_on_failure	Set whether a notification is sent globally when a decorated function fails.
set_failure_notification_level	Set the global default notification level used when a decorated function fails.
notify	Send a one-shot notification without creating a persistent notifier.
notify_on_completion	Send a notification when the decorated function finishes.

Description

Desktop and multi-channel notification support for PyAnsys libraries.

This module exposes AnsysNotifier for persistent use inside PyAnsys library workflows and the convenience function notify() for one-shot script usage.

Install the optional dependency before using this module:

pip install "ansys-tools-common[notifications]"

Quick start

>>> from ansys.tools.common.notifications import notify, NotificationType
>>> notify("Simulation complete.")
>>> notify("Solve diverged!", notification_type=NotificationType.FAILURE)
>>> from ansys.tools.common.notifications import NotificationChannel
>>> notify("Job done.", channels=[NotificationChannel.WINDOWS])

Module detail

notifications.get_notification_channels() → list[str] | None

Return the global default notification channels.

Returns

list[str] | None

The channels set by set_notification_channels(), or None if no global default is set (desktop channel will be used).

notifications.get_notification_level() → NotificationType

Return the global default notification level.

Returns

NotificationType

The level set by set_notification_level().

notifications.get_notify_on_failure() → bool

Return the global default for whether failure notifications are sent.

Returns

bool

The value set by set_notify_on_failure().

notifications.get_failure_notification_level() → NotificationType

Return the global default notification level used on failure.

Returns

NotificationType

The level set by set_failure_notification_level().

notifications.set_notification_channels(channels: list[NotificationChannel | str] | None) → None

Set the global default notification channels.

Affects all subsequent calls to notify() and notify_on_completion() that do not supply an explicit channels argument. Setting channels to None reverts to the automatically detected desktop channel.

Parameters

channelslist[NotificationChannel | str] | None

A list of apprise-compatible channel URLs or NotificationChannel members, or None to reset to the OS desktop default.

Examples

>>> set_notification_channels([NotificationChannel.SLACK + "token/channel"])
>>> set_notification_channels(["myfancychannel", "anotherchannel"])
>>> set_notification_channels(None)  # reset to desktop default

notifications.set_notification_level(level: NotificationType | str) → None

Set the global default notification level.

Affects all subsequent calls to notify() and notify_on_completion() that do not supply an explicit notification_type argument.

Parameters

levelNotificationType | str

A NotificationType member or its string value ("info", "success", "warning", "failure").

Examples

>>> set_notification_level("warning")
>>> set_notification_level(NotificationType.FAILURE)

notifications.set_notify_on_failure(enabled: bool) → None

Set whether a notification is sent globally when a decorated function fails.

Affects all subsequent calls to notify_on_completion() that do not supply an explicit notify_on_failure argument.

Parameters

enabledbool

True to send a failure notification (default), False to suppress it.

Examples

>>> set_notify_on_failure(False)

notifications.set_failure_notification_level(level: NotificationType | str) → None

Set the global default notification level used when a decorated function fails.

Affects all subsequent calls to notify_on_completion() that do not supply an explicit failure_notification_type argument.

Parameters

levelNotificationType | str

A NotificationType member or its string value ("info", "success", "warning", "failure").

Examples

>>> set_failure_notification_level("warning")
>>> set_failure_notification_level(NotificationType.FAILURE)

notifications.notify(message: str, title: str = 'PyAnsys', channels: list[NotificationChannel | str] | None = None, format: NotificationFormat = NotificationFormat.TEXT, notification_type: NotificationType | None = None) → bool

Send a one-shot notification without creating a persistent notifier.

This convenience function is intended for simple script usage where a persistent AnsysNotifier instance is not needed.

Parameters

messagestr

Body of the notification.

titlestr, optional

Notification title, by default "PyAnsys".

channelslist[NotificationChannel | str] | None, optional

Apprise channel URLs. When None, the global default set by set_notification_channel() is used; if that is also None, the native desktop notification service for the current OS is used.

formatNotificationFormat, optional

Body format, by default NotificationFormat.TEXT.

notification_typeNotificationType | None, optional

notification_type level. When None, the global default set by set_notification_level() is used (initially NotificationType.INFO).

Returns

bool

True if delivered successfully to all channels.

Examples

Minimal usage — sends a desktop notification:

>>> from ansys.tools.common.notifications import notify
>>> notify("Simulation complete.")

Failure notification:

>>> notify("Solve diverged!", notification_type=NotificationType.FAILURE)

Multi-channel:

>>> notify("Job done.", channels=[NotificationChannel.WINDOWS, NotificationChannel.SLACK + "token/channel"])

notifications.notify_on_completion(message: str | None = None, *, title: str = 'PyAnsys', channels: list[NotificationChannel | str] | None = None, format: NotificationFormat = NotificationFormat.TEXT, notification_type: NotificationType | None = None, notify_on_failure: bool | None = None, failure_notification_type: NotificationType | None = None, failure_message: str | None = None) → collections.abc.Callable

Send a notification when the decorated function finishes.

Wraps a callable so that a notification is dispatched automatically on success (and optionally on failure) without any extra code at each call site.

Parameters

messagestr | None, optional

Body of the notification. When None a default message is built from the wrapped function’s name: " completed.".

titlestr, optional

Notification title, by default "PyAnsys".

channelslist[NotificationChannel | str] | None, optional

Apprise channel URLs. When None, the global default set by set_notification_channel() is used; if that is also None, the native desktop notification service for the current OS is used.

formatNotificationFormat, optional

Body format, by default NotificationFormat.TEXT.

notification_typeNotificationType | None, optional

Notification type used for the notification. When None, the global default set by set_notification_level() is used (initially NotificationType.INFO).

notify_on_failurebool | None, optional

When True a notification is also sent if the wrapped function raises an exception. The exception is always re-raised. When None, the global default set by set_notify_on_failure() is used (initially True).

failure_notification_typeNotificationType | None, optional

Notification type used for the failure notification. When None, the global default set by set_failure_notification_level() is used (initially NotificationType.FAILURE).

failure_messagestr | None, optional

Body of the failure notification. When None a default message is built from the wrapped function’s name and the exception: " failed: ".

Returns

Callable

A decorator that wraps the target function.

Examples

Send a desktop notification when the function returns:

>>> from ansys.tools.common.notifications import notify_on_completion
>>> @notify_on_completion("Simulation complete.")
... def run_simulation():
...     pass

Auto-generate the message from the function name:

>>> @notify_on_completion()
... def solve():
...     pass

Custom channels and failure notification:

>>> @notify_on_completion(
...     channels=[NotificationChannel.SLACK + "token/channel"],
...     notify_on_failure=True,
... )
... def long_running_job():
...     pass