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.

    This compares palettes, not layouts, so order is never compared: two
    orderings of one palette are the same palette. For an ordered
    comparison, use ``a.colors == b.colors``. 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,
        unicode_name=record.unicode_name or record.name,
        category=record.category,
        disposition=record.disposition,
        replaced_by=record.replaced_by,
        static_mode=record.static_mode,
        dynamic_mode=record.dynamic_mode,
        tags=record.tags,
    )

@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, Space and Worldly.

    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.
    """
    slugs = cls._require_category_slugs(category)
    return {slug: cls.get(slug) for slug in sorted(slugs)}

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

    Tags are the LIFX app's search tags, such as ``"Calm"`` or
    ``"Date night"``. A theme with no app source carries none.

    Returns:
        Distinct tags, sorted case-insensitively.
    """
    return sorted({tag for r in cls._records() for tag in r.tags}, key=tag_sort_key)

@classmethod
def get_by_tag(cls, tag: str) -> dict[str, Theme]:
    """Get all themes carrying a tag.

    Args:
        tag: Tag name. Matching is case- and punctuation-insensitive:
            both sides are normalised by the slug rule, so
            ``"Date night"``, ``"date night"`` and ``"date_night"`` all
            resolve.

    Returns:
        Dictionary of Theme objects keyed by slug and sorted by slug.

    Raises:
        ValueError: If ``tag`` is not a string, or matches no tag in the
            library. The message lists the tags that exist.
    """
    return {slug: cls.get(slug) for slug in sorted(cls._require_tag_slugs(tag))}

@classmethod
def find(
    cls,
    *,
    tags: Iterable[str] = (),
    match: Literal["all", "any"] = "all",
    category: str | None = None,
    static_mode: str | None = None,
) -> dict[str, Theme]:
    """Find themes by tags, category and static mode together.

    Every given criterion must hold. ``match`` decides only how the
    tags combine: ``"all"`` requires every tag, ``"any"`` at least one.
    With no criteria, every theme is returned.

    Args:
        tags: Tag names, matched as ``get_by_tag()`` matches them.
        match: ``"all"`` or ``"any"``.
        category: Category name, matched as ``get_by_category()``
            matches it.
        static_mode: Exact static mode, such as ``"grid_static"``.

    Returns:
        Dictionary of matching Theme objects keyed by slug and sorted by
        slug; empty when valid criteria select nothing.

    Raises:
        TypeError: If ``tags`` is a single string rather than an
            iterable of tags.
        ValueError: If ``match`` is invalid, or a tag, category or
            static mode names nothing in the library.

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

        tags = ThemeLibrary.get_tags()
        if "Calm" in tags:
            calm = ThemeLibrary.find(tags=["Calm"])
        blended = ThemeLibrary.find(static_mode="blended")
        ```
    """
    if isinstance(tags, str):
        raise TypeError(
            "tags must be an iterable of tags, not a single string; "
            "pass ['Calm'] for one tag"
        )
    if match not in ("all", "any"):
        raise ValueError(f"match must be 'all' or 'any', got {match!r}")
    records = cls._records()
    selected = {r.slug for r in records}
    tag_sets = [cls._require_tag_slugs(tag) for tag in tags]
    if tag_sets:
        if match == "all":
            selected &= set.intersection(*tag_sets)
        else:
            selected &= set.union(*tag_sets)
    if category is not None:
        selected &= cls._require_category_slugs(category)
    if static_mode is not None:
        modes = sorted({r.static_mode for r in records})
        if static_mode not in modes:
            raise ValueError(
                f"static_mode '{static_mode}' is not recognised. "
                f"Available static modes: {', '.join(modes) or '(none)'}"
            )
        selected &= {r.slug for r in records if r.static_mode == static_mode}
    return {slug: cls.get(slug) for slug in sorted(selected)}

def get_multizone_colors(self, zone_count: int, brightness: float) -> list[HSBK]:
    """Colours for a strip, one per zone.

    Args:
        zone_count: Number of zones to fill
        brightness: The light's current brightness, 0.0 to 1.0

    Returns:
        One colour per zone
    """
    if self._mode == "blended":
        colors = self._gradient(self._shuffled(self._colors), zone_count)
    elif self._mode == "solid":
        colors = self._stretch(
            self._shuffled(self._distinct(self._colors)), zone_count
        )
    else:
        colors = self._stretch(self._colors, zone_count)
    return self._rescale(colors, brightness)

def get_matrix_colors(
    self, width: int, height: int, brightness: float, *, vertical: bool = False
) -> list[HSBK]:
    """Colours for one matrix light, in row-major order.

    Args:
        width: Pixels per row, as the device reports
        height: Rows, as the device reports
        brightness: The light's current brightness, 0.0 to 1.0
        vertical: Paint stripe moods as bands along the long axis, as the
            app does on every Candle, the Tube and the Mirror

    Returns:
        ``width * height`` colours
    """
    return self._rescale(self._paint(width, height, vertical=vertical), brightness)

def get_chain_colors(
    self, tile_count: int, width: int, height: int, brightness: float
) -> list[list[HSBK]]:
    """Colours for a Tile chain, laid out in chain order.

    The app ignores where the tiles sit: one canvas ``width * tile_count``
    wide is painted and sliced per tile. A blended mood paints each tile
    on its own.

    Args:
        tile_count: Tiles in the chain
        width: Pixels per row of one tile
        height: Rows of one tile
        brightness: The light's current brightness, 0.0 to 1.0

    Returns:
        Per tile, ``width * height`` colours in row-major order
    """
    if self._mode == "blended":
        tiles = [
            self._blended_matrix(self._colors, width, height)
            for _ in range(tile_count)
        ]
    else:
        canvas_width = width * tile_count
        canvas = self._paint(canvas_width, height)
        tiles = [
            [
                canvas[row * canvas_width + tile * width + col]
                for row in range(height)
                for col in range(width)
            ]
            for tile in range(tile_count)
        ]
    flat = self._rescale([c for tile in tiles for c in tile], brightness)
    size = width * height
    return [flat[i * size : (i + 1) * size] for i in range(tile_count)]

def get_bulb_colors(self, brightnesses: Sequence[float]) -> list[HSBK]:
    """Deal the theme's distinct colours, shuffled, one per bulb in turn.

    Args:
        brightnesses: Each bulb's current brightness, in bulb order

    Returns:
        One colour per bulb, rescaled to that bulb's brightness
    """
    deck = self._shuffled(self._distinct(self._colors))
    dealt: list[HSBK] = []
    for index, brightness in enumerate(brightnesses):
        # Rescale the whole deck so each bulb keeps the theme's relative
        # brightness, then take this bulb's card.
        dealt.append(self._rescale(deck, brightness)[index % len(deck)])
    return dealt

def get_palette(self, brightness: float) -> list[HSBK]:
    """The theme's colours, in order, rescaled to the light's brightness.

    An animated mood steps through these: a bulb's colour loop and a
    matrix light's firmware MORPH, as the app rescales them.

    Args:
        brightness: The light's brightness, 0.0 to 1.0. At 0.0 the
            colours are returned unchanged.

    Returns:
        One colour per theme colour, the brightest at ``brightness``
    """
    return self._rescale(self._colors, brightness)

@staticmethod
def morph_palette(colors: Sequence[HSBK]) -> list[HSBK]:
    """Reduce a palette to what firmware MORPH can carry.

    The app's run-weighted reduction: deterministic, so only the order
    the caller shuffles it into varies.

    Args:
        colors: Palette in source order

    Returns:
        The palette unchanged when it fits, else ``MAX_PALETTE_COLORS``
        colours weighted by the area each run covers
    """
    if len(colors) <= MAX_PALETTE_COLORS:
        return list(colors)
    return MoodGenerator._stretch(colors, MAX_PALETTE_COLORS)