"""Main message interface - equivalent to C++ IMainMessage."""

from __future__ import annotations

from abc import ABC, abstractmethod
from typing import Protocol


class IMainMessage(ABC):
    """Abstract base class for message handlers.

    This interface handles message processing and distribution,
    equivalent to the C++ IMainMessage interface.
    """

    @abstractmethod
    def init(self) -> None:
        """Initialize the message handler.

        Sets up message subscriptions and handlers.
        """

    @abstractmethod
    def handle_message(self, message: str, value: int = 0, param: object = None) -> None:
        """Handle incoming message.

        Args:
            message: Message identifier
            value: Integer value associated with message
            param: Additional parameter data
        """

    @abstractmethod
    def get_message_count(self) -> int:
        """Get the number of handled messages.

        Returns
        -------
            int: Total number of message types this handler processes
        """

    @abstractmethod
    def get_message_id(self, index: int) -> str:
        """Get message ID by index.

        Args:
            index: Message index (0-based)

        Returns
        -------
            str: Message identifier at the given index
        """


# Protocol version for type checking
class MainMessageProtocol(Protocol):
    """Protocol for message handler type checking."""

    def init(self) -> None:
        """Initialize the message handler.

        Sets up message subscriptions and handlers.
        """

    def handle_message(self, message: str, value: int, param: object) -> None:
        """Handle incoming message.

        Args:
            message: Message identifier
            value: Integer value associated with message
            param: Additional parameter data
        """

    def get_message_count(self) -> int:
        """Get the number of handled messages.

        Returns
        -------
            int: Total number of message types this handler processes
        """

    def get_message_id(self, index: int) -> str:
        """Get message ID by index.

        Args:
            index: Message index (0-based)

        Returns
        -------
            str: Message identifier at the given index
        """
