:class:`AnsysNotifier`
======================


.. py:class:: ansys.tools.common.notifications.AnsysNotifier(channels: list[NotificationChannel | str] | None = None, title: str = 'PyAnsys', format: NotificationFormat = NotificationFormat.TEXT, notification_type: NotificationType = NotificationType.INFO)

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

   :class:`AnsysNotifier` wraps `apprise <https://github.com/caronc/apprise>`_
   to provide a unified notification API across 100+ channels including native
   desktop toast notifications (Windows, macOS, Linux) and external services
   such as email, Slack, Microsoft Teams, and Telegram.

   Parameters
   ----------
   channels : list[NotificationChannel | str] | None, optional
       List of apprise-compatible channel URLs.  When ``None`` or empty the
       native desktop notification service for the current OS is used
       automatically (Windows toast, macOS Notification Center, Linux D-Bus).

       Use :class:`NotificationChannel` members for the common schemes, or
       pass a plain :class:`str` for any URL supported by apprise::

           NotificationChannel.WINDOWS  # Windows 10/11 toast
           NotificationChannel.DBUS  # Linux (GNOME / KDE)
           NotificationChannel.MACOS  # macOS Notification Center
           NotificationChannel.MAILTO + "user:pass@gmail.com"  # Gmail
           NotificationChannel.MAILTOS + "user:pass@smtp.corp.com"  # SMTP/TLS
           NotificationChannel.SLACK + "token/channel"  # Slack
           NotificationChannel.MSTEAMS + "A/B/C/D"  # MS Teams
           "tgram://bot_token/chat_id"  # Telegram (plain str)

       See https://appriseit.com/ for the full list.
   title : str, optional
       Default notification title, by default ``"PyAnsys"``.
   format : NotificationFormat, optional
       Default body format, by default :attr:`NotificationFormat.TEXT`.
   notification_type : NotificationType, optional
       Default notification_type level, by default :attr:`NotificationType.INFO`.

   Examples
   --------
   Standalone one-liner (desktop notification, auto-detected OS):

   >>> notifier = AnsysNotifier()
   >>> notifier.notify("Simulation complete.")

   Integration inside a PyAnsys library, with a product-specific title and a
   success notification_type:

   >>> from ansys.tools.common.notifications import AnsysNotifier, NotificationType
   >>> _notifier = AnsysNotifier(title="PyMAPDL", notification_type=NotificationType.SUCCESS)
   >>> _notifier.notify("Solve finished in 42 iterations.")

   Multi-channel (desktop + email):

   >>> notifier = AnsysNotifier(
   ...     channels=[NotificationChannel.WINDOWS, NotificationChannel.MAILTOS + "user:pass@smtp.company.com"]
   ... )
   >>> notifier.notify("Job converged.")

   HTML-formatted notification:

   >>> from ansys.tools.common.notifications import NotificationFormat
   >>> notifier = AnsysNotifier(format=NotificationFormat.HTML)
   >>> notifier.notify("<b>Residual:</b> 1.23e-6 &mdash; converged.")



.. py:currentmodule:: AnsysNotifier

Overview
--------

.. tab-set::



   .. tab-item:: Methods

      .. list-table::
          :header-rows: 0
          :widths: auto

          * - :py:attr:`~add_channel`
            - Add a notification channel.
          * - :py:attr:`~notify`
            - Send a notification to all registered channels.


   .. tab-item:: Properties

      .. list-table::
          :header-rows: 0
          :widths: auto

          * - :py:attr:`~title`
            - Default title applied to all notifications from this instance.
          * - :py:attr:`~format`
            - Default body format applied to all notifications from this instance.
          * - :py:attr:`~notification_type`
            - Default notification_type applied to all notifications from this instance.







Import detail
-------------

.. code-block:: python

    from ansys.tools.common.notifications import AnsysNotifier

Property detail
---------------

.. py:property:: title
   :type: str


   Default title applied to all notifications from this instance.


.. py:property:: format
   :type: NotificationFormat


   Default body format applied to all notifications from this instance.


.. py:property:: notification_type
   :type: NotificationType


   Default notification_type applied to all notifications from this instance.





Method detail
-------------

.. py:method:: add_channel(url: str) -> bool

   Add a notification channel.

   Parameters
   ----------
   url : str
       An apprise-compatible notification URL.

   Returns
   -------
   bool
       ``True`` if the channel was accepted, ``False`` if the URL was
       invalid or a required backend library is not installed.

   Examples
   --------
   >>> notifier = AnsysNotifier(channels=[])
   >>> notifier.add_channel(NotificationChannel.SLACK + "token/channel")
   True


.. py:method:: notify(message: str, title: str | None = None, format: NotificationFormat | None = None, notification_type: NotificationType | None = None) -> bool

   Send a notification to all registered channels.

   Parameters
   ----------
   message : str
       Body of the notification.
   title : str | None, optional
       Overrides the instance-level :attr:`title` for this call only.
   format : NotificationFormat | None, optional
       Overrides the instance-level :attr:`format` for this call only.
   notification_type : NotificationType | None, optional
       Overrides the instance-level :attr:`notification_type` for this call only.

   Returns
   -------
   bool
       ``True`` if every channel accepted the notification, ``False`` if
       at least one channel failed.

   Examples
   --------
   Basic informational notification:

   >>> notifier.notify("Solve complete.")

   Failure notification with a per-call notification_type override:

   >>> notifier.notify("Divergence detected.", notification_type=NotificationType.FAILURE)

   Success notification with a per-call title override:

   >>> notifier.notify("Converged in 42 steps.", title="MyApp", notification_type=NotificationType.SUCCESS)