"""Object creator interface - equivalent to C++ IObjectCreator."""

from __future__ import annotations

from abc import ABC, abstractmethod
from typing import Protocol


class IObjectCreator(ABC):
    """Abstract base class for object creators.

    This interface handles dynamic object creation and management,
    equivalent to the C++ IObjectCreator interface.
    """

    @abstractmethod
    def init(self) -> None:
        """Initialize the object creator.

        Sets up object factory mappings and registrations.
        """

    @abstractmethod
    def get_object_count(self) -> int:
        """Get the number of creatable objects.

        Returns
        -------
            int: Total number of object types this creator can produce
        """

    @abstractmethod
    def get_object_ptr(self, object_name: str) -> object | None:
        """Get object instance by name.

        Args:
            object_name: Name/identifier of the object to create

        Returns
        -------
            object | None: Created object instance or None if not found
        """

    @abstractmethod
    def get_object_name(self, index: int) -> str:
        """Get object name by index.

        Args:
            index: Object index (0-based)

        Returns
        -------
            str: Object name at the given index
        """

    @abstractmethod
    def refresh(self) -> None:
        """Refresh/create objects periodically.

        Called for periodic object updates or recreation.
        """


# Protocol version for type checking
class ObjectCreatorProtocol(Protocol):
    """Protocol for object creator type checking."""

    def init(self) -> None:
        """Initialize the object creator.

        Sets up object factory mappings and registrations.
        """

    def get_object_count(self) -> int:
        """Get the number of creatable objects.

        Returns
        -------
            int: Total number of object types this creator can produce
        """

    def get_object_ptr(self, object_name: str) -> object | None:
        """Get object instance by name.

        Args:
            object_name: Name/identifier of the object to create

        Returns
        -------
            object | None: Created object instance or None if not found
        """

    def get_object_name(self, index: int) -> str:
        """Get object name by index.

        Args:
            index: Object index (0-based)

        Returns
        -------
            str: Object name at the given index
        """

    def refresh(self) -> None:
        """Refresh/create objects periodically.

        Called for periodic object updates or recreation.
        """
