Themes API Reference¶

def add_color(self, color: HSBK) -> None:
    """Add a color to the theme.

    Args:
        color: HSBK color to add

    Example:
        ```python
        theme = Theme()
        theme.add_color(HSBK(hue=0, saturation=1.0, brightness=1.0, kelvin=3500))
        ```
    """
    self.colors.append(color)

def random(self) -> HSBK:
    """Get a random color from the theme.

    Returns:
        A random HSBK color from the theme

    Example:
        ```python
        theme = Theme([red, green, blue])
        color = theme.random()
        ```
    """
    return random.choice(self.colors)

def shuffled(self) -> Theme:
    """Get a new theme with colors in random order.

    Returns:
        New Theme instance with shuffled colors

    Example:
        ```python
        theme = Theme([color1, color2, color3])
        shuffled_theme = theme.shuffled()
        ```
    """
    shuffled_colors = self.colors.copy()
    random.shuffle(shuffled_colors)
    return Theme(shuffled_colors)

def get_next_bounds_checked(self, index: int) -> HSBK:
    """Get the next color after index or the last color if at end.

    Args:
        index: Index of current color

    Returns:
        Next HSBK color or the last color if index is at the end

    Example:
        ```python
        theme = Theme([red, green, blue])
        color = theme.get_next_bounds_checked(0)  # green
        color = theme.get_next_bounds_checked(2)  # blue (last color)
        ```
    """
    if index + 1 < len(self.colors):
        return self.colors[index + 1]
    return self.colors[-1]

def ensure_color(self) -> None:
    """Ensure the theme has at least one color.

    If the theme is empty, adds a default white color.
    """
    if not self.colors:
        self.colors.append(
            HSBK(hue=0, saturation=0, brightness=1.0, kelvin=3500)
        )  # pragma: no cover

def __len__(self) -> int:
    """Get the number of colors in the theme."""
    return len(self.colors)

def __iter__(self) -> Iterator[HSBK]:
    """Iterate over colors in the theme."""
    return iter(self.colors)

def __getitem__(self, index: int) -> HSBK:
    """Get a color by index.

    Args:
        index: Index of the color (0-based)

    Returns:
        HSBK color at the given index

    Raises:
        IndexError: If index is out of range

    Example:
        ```python
        theme = Theme([red, green, blue])
        color = theme[1]  # green
        ```
    """
    return self.colors[index]

def __contains__(self, color: HSBK) -> bool:
    """Check if a color is in the theme.

    Args:
        color: HSBK color to check

    Returns:
        True if color is in theme (by value comparison)

    Example:
        ```python
        theme = Theme([red, green, blue])
        if red in theme:
            print("Red is in the theme")
        ```
    """
    return any(c == color for c in self.colors)

def palette_equals(self, other: Theme) -> bool:
    """Check whether two themes carry the same palette.

    Order is never compared because the app shuffles palette order on
    every application, so two orderings of one palette are the same
    palette. Identity (slug, name, category, disposition and
    replaced_by) is excluded too: an identity-bearing library theme and
    a caller-built theme with the same colors have the same palette.
    Colors compare at uint16 (protocol) granularity via HSBK equality,
    and duplicate counts matter — a multiset comparison, not a set
    comparison.

    This is deliberately a named method rather than ``__eq__``. A
    Theme's palette is mutable via ``add_color()``, so value equality
    could not be paired with a stable ``__hash__``; making ``==``
    compare palettes would leave Theme unhashable and silently change
    what ``theme in [a, b]``, ``list.index()`` and ``list.remove()``
    mean. ``==`` therefore stays identity comparison and the palette
    comparison is spelled out at the call site.

    Args:
        other: Theme to compare palettes with.

    Returns:
        True if both palettes are the same multiset of colors.

    Example:
        ```python
        # independence and old_glory ship one shared app palette
        assert ThemeLibrary.get("independence").palette_equals(
            ThemeLibrary.get("old_glory")
        )
        ```
    """
    if not isinstance(other, Theme):
        raise TypeError(
            f"palette_equals() expects a Theme, got {type(other).__name__}"
        )
    return Counter(self.colors) == Counter(other.colors)

def __repr__(self) -> str:
    """Return a string representation of the theme."""
    color_count = len(self.colors)
    return f"Theme({color_count} colors)"

@classmethod
def get(cls, name: str) -> Theme:
    """Get a theme by name.

    Args:
        name: Theme name (case-insensitive)

    Returns:
        Theme object

    Raises:
        KeyError: If theme name is not found

    Example:
        ```python
        from lifx.theme import ThemeLibrary

        evening_theme = ThemeLibrary.get("evening")
        await light.apply_theme(evening_theme, power_on=True)
        ```
    """
    record = cls._THEMES.get(name.lower())
    if record is None:
        raise KeyError(
            f"Theme '{name}' not found. Use "
            f"ThemeLibrary.get_available_themes() to list the "
            f"available themes."
        )
    # Theme.__init__ copies the palette, so mutating a returned Theme can
    # never corrupt the library's own record.
    return Theme(
        list(record.colors),
        slug=record.slug,
        name=record.name,
        category=record.category,
        disposition=record.disposition,
        replaced_by=record.replaced_by,
    )

@classmethod
def get_available_themes(cls) -> list[str]:
    """Get all available themes by name.

    Returns:
        Sorted list of theme names

    Example:
        ```python
        from lifx.theme import ThemeLibrary

        all_themes = ThemeLibrary.get_available_themes()
        for theme_name in all_themes:
            print(f"- {theme_name}")
        ```
    """
    return sorted(cls._THEMES)

@classmethod
def get_categories(cls) -> list[str]:
    """Get every category present in the library's data.

    Returns:
        Sorted ``list[str]`` of the category names present in the
        library's theme records.

    Example:
        ```python
        from lifx.theme import ThemeLibrary

        for category in ThemeLibrary.get_categories():
            print(f"- {category}")
        ```
    """
    return sorted({record.category for record in cls._THEMES.values()})

@classmethod
def get_by_category(cls, category: str) -> dict[str, Theme]:
    """Get all themes in a category.

    Args:
        category: Category name. Matching is case- and punctuation-
            insensitive: both sides are normalised by the slug rule, so
            ``"Art Series"``, ``"art series"`` and ``"art_series"`` all
            resolve. The categories are Archives, Art Series, Holidays,
            Library (pre-6.3.0 keys with no app counterpart, defined by
            this library rather than the LIFX app), Moods, Music, Nature,
            Play and Space.

    Returns:
        Dictionary of Theme objects in the category, keyed by slug and
        sorted by slug.

    Raises:
        ValueError: If ``category`` is not a string, or names no category
            in the library. The pre-6.4.0 names (``seasonal``, ``holiday``,
            ``mood``, ``ambient``, ``functional``, ``atmosphere``) are
            among the unrecognised: they were never a taxonomy this data
            carries, and the message lists the categories that exist.
    """
    if type(category) is not str:
        # derive_slug() would raise AttributeError on a non-string, which
        # contradicts the documented ValueError and reads as a library
        # bug rather than a bad argument.
        raise ValueError(
            f"Category must be a string, got {type(category).__name__}. "
            f"Available categories: {', '.join(cls.get_categories())}"
        )

    slugs = cls._slugs_for_category(derive_slug(category))
    if not slugs:
        raise ValueError(
            f"Category '{category}' is not recognised. "
            f"Available categories: {', '.join(cls.get_categories())}"
        )
    return {slug: cls.get(slug) for slug in sorted(slugs)}