"""
Tarot namespace API.

Unified accessor for Tarot-related data and operations.

Usage:
    from tarot import Tarot

    # Deck and cards
    card = Tarot.deck.card(3)
    major5 = Tarot.deck.card.major(5)
    cups2 = Tarot.deck.card.minor.cups(2)

    # Letters (Hebrew with correspondences)
    letter = Tarot.letters('aleph')
    simple_letters = Tarot.letters.filter(letter_type="Simple")
    all_letters = Tarot.letters.display_all()

    # Tree of Life
    sephera = Tarot.tree.sephera(1)
    path = Tarot.tree.path(11)

    # Cube of Space
    wall = Tarot.cube.wall('North')
    area = Tarot.cube.area('North', 'center')
"""

from typing import TYPE_CHECKING, Dict, Optional, Union, overload

from kaballah import Cube, Tree
from letter import letters

from .card import CardAccessor

if TYPE_CHECKING:
    from utils.attributes import God, Planet

    from .attributes import Hexagram
    from .card.data import CardDataLoader


class DeckAccessor:
    """Accessor for deck and card operations."""

    # Card accessor (Tarot.deck.card, Tarot.deck.card.major, etc.)
    card = CardAccessor()

    def __str__(self) -> str:
        """Return a nice summary of the deck accessor."""
        return (
            "Tarot Deck Accessor\n\n"
            "Access methods:\n"
            "  Tarot.deck.card(3)              - Get card by number\n"
            "  Tarot.deck.card.filter(...)     - Filter cards\n"
            "  Tarot.deck.card.display()       - Display all cards\n"
            "  Tarot.deck.card.spread(...)     - Draw a spread"
        )

    def __repr__(self) -> str:
        """Return a nice representation of the deck accessor."""
        return self.__str__()


class Tarot:
    """
    Unified accessor for Tarot correspondences and data.

    Provides access to cards, letters, tree of life, and cube of space.

    Temporal and astrological functions are available through the temporal module:
        from temporal import ThalemaClock, Zodiac

    Attributes:
        deck: CardAccessor for card operations
        letters: Hebrew letter accessor
        tree: Tree of Life accessor
        cube: Cube of Space accessor
    """

    deck = DeckAccessor()
    letters = letters()
    tree = Tree
    cube = Cube

    _loader: Optional["CardDataLoader"] = None  # type: ignore
    _initialized: bool = False

    @classmethod
    def _ensure_initialized(cls) -> None:
        """Lazy-load CardDataLoader on first access."""
        if cls._initialized:
            return

        from .card.data import CardDataLoader

        cls._loader = CardDataLoader()
        cls._initialized = True

    @classmethod
    @overload
    def planet(cls, name: str) -> Optional["Planet"]: ...

    @classmethod
    @overload
    def planet(cls, name: None = ...) -> Dict[str, "Planet"]: ...

    @classmethod
    def planet(cls, name: Optional[str] = None) -> Union[Optional["Planet"], Dict[str, "Planet"]]:
        """Return a planet entry or all planets."""
        cls._ensure_initialized()
        return cls._loader.planet(name)  # type: ignore

    @classmethod
    def god(cls, name: Optional[str] = None) -> Union[Optional["God"], Dict[str, "God"]]:
        """Return a god entry or all gods."""
        cls._ensure_initialized()
        return cls._loader.god(name)  # type: ignore

    @classmethod
    def hexagram(
        cls, number: Optional[int] = None
    ) -> Union[Optional["Hexagram"], Dict[int, "Hexagram"]]:
        """Return a hexagram or all hexagrams."""
        cls._ensure_initialized()
        return cls._loader.hexagram(number)  # type: ignore
