import random
from enum import IntEnum
from typing import Optional, TypeVar

__all__ = ["IconData"]

T = TypeVar("T", bound="IconData")


class IconData(IntEnum):
    """
    Represents an icon used in the UI.

    An icon can come from:

    - the Material icon set via the [`Icons`][flet.Icons] enum,
    - the Cupertino icon set via the [`CupertinoIcons`][flet.CupertinoIcons] enum,
    - or a custom icon set defined by the developer.

    Internally, an icon is stored as a 32-bit integer that encodes both the icon's
    code point and its originating icon set.

    Encoding structure:

    - Lower 24 bits (bits 0-23): the icon's code point.
    - Third byte (bits 24-32): the icon set identifier (set ID),
        which distinguishes between icon sets like Material, Cupertino, etc.

    This encoding scheme allows a single integer to uniquely represent any icon
    across multiple icon sets.
    """

    @classmethod
    def random(
        cls: type[T],
        exclude: Optional[list[T]] = None,
        weights: Optional[dict[T, int]] = None,
    ) -> Optional[T]:
        """
        Selects a random icon from the subclass enum, with optional
        exclusions and weights.
        """
        choices = list(cls)
        if exclude:
            choices = [member for member in choices if member not in exclude]
            if not choices:
                return None
        if weights:
            weights_list = [weights.get(c, 1) for c in choices]
            return random.choices(choices, weights=weights_list)[0]
        return random.choice(choices)