Source code for Karana.KUtils.MultibodyTUI.notify

# Copyright (c) 2024-2026 Karana Dynamics Pty Ltd. All rights reserved.
#
# NOTICE TO USER:
#
# This source code and/or documentation (the "Licensed Materials") is
# the confidential and proprietary information of Karana Dynamics Inc.
# Use of these Licensed Materials is governed by the terms and conditions
# of a separate software license agreement between Karana Dynamics and the
# Licensee ("License Agreement"). Unless expressly permitted under that
# agreement, any reproduction, modification, distribution, or disclosure
# of the Licensed Materials, in whole or in part, to any third party
# without the prior written consent of Karana Dynamics is strictly prohibited.
#
# THE LICENSED MATERIALS ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND.
# KARANA DYNAMICS DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
# BUT NOT LIMITED TO WARRANTIES OF MERCHANTABILITY, NON-INFRINGEMENT, AND
# FITNESS FOR A PARTICULAR PURPOSE.
#
# IN NO EVENT SHALL KARANA DYNAMICS BE LIABLE FOR ANY DAMAGES WHATSOEVER,
# INCLUDING BUT NOT LIMITED TO LOSS OF PROFITS, DATA, OR USE, EVEN IF
# ADVISED OF THE POSSIBILITY OF SUCH DAMAGES, WHETHER IN CONTRACT, TORT,
# OR OTHERWISE ARISING OUT OF OR IN CONNECTION WITH THE LICENSED MATERIALS.
#
# U.S. Government End Users: The Licensed Materials are a "commercial item"
# as defined at 48 C.F.R. 2.101, and are provided to the U.S. Government
# only as a commercial end item under the terms of this license.
#
# Any use of the Licensed Materials in individual or commercial software must
# include, in the user documentation and internal source code comments,
# this Notice, Disclaimer, and U.S. Government Use Provision.

"""Notifier class to create TUI notifications."""

import logging
from typing import Callable

from .terminal import critical, error, warn, info




class Notifier:
    """Helper to maintain a single, current notification message.

    The notification is replaced whenever a new notification is
    triggered with the same or higher priority.
    """

    def __init__(self, on_notify: Callable | None = None):
        """Create an instance of Notifier.

        Parameters
        ----------
        on_notify: Callable | None
            Optional callable invoked whenever the notification changes
        """
        self._message = ""
        self._priority = logging.NOTSET
        self._on_notify = on_notify

    @property
    def message(self):
        """Return the current notification message."""
        return self._message



    def __str__(self):
        """Return the Current notification message."""
        return self.message




    def __call__(self, message: str):
        """Notify an info message."""
        self.info(message)


    def _replace(self, message: str, priority: int):
        """Replace the notification if it has equal or higher priority.

        Parameters
        ----------
        message: str
            The notification message
        priority: int
            The notification priority from the range in the standard logging
            library's constants
        """
        if priority >= self._priority:
            self._message = message
            self._priority = priority
            if self._on_notify:
                self._on_notify()



    def critical(self, message: str):
        """Notify a critical error message."""
        self._replace(critical(message), logging.CRITICAL)




    def error(self, message: str):
        """Notify an error message."""
        self._replace(error(message), logging.ERROR)




    def warn(self, message: str):
        """Notify a warn message."""
        self._replace(warn(message), logging.WARNING)




    def info(self, message: str):
        """Notify an info message."""
        self._replace(info(message), logging.INFO)




    def clear(self):
        """Reset the notification message."""
        self._message = ""
        self._priority = logging.NOTSET
        if self._on_notify:
            self._on_notify()




    def clearPriority(self):
        """Reset the notification message priority.

        This will keep the current message but allow lower priority
        messages to replace it.
        """
        self._priority = logging.NOTSET