lifx-async 4.6.1__tar.gz → 4.7.0__tar.gz

{lifx_async-4.6.1 → lifx_async-4.7.0}/CLAUDE.md

@@ -459,6 +459,22 @@ async with await MultiZoneLight.from_ip("192.168.1.100") as light:
 - `get_extended_color_zones(start, end)`: Direct access to extended multizone protocol (requires extended capability)
 - `get_color_zones(start, end)`: Direct access to standard multizone protocol (works on all multizone devices)
 
+**Fire-and-forget mode for animations:**
+
+For high-frequency animations (>20 updates/second), use the `fast=True` parameter to skip waiting for device acknowledgement:
+
+```python
+# Standard mode (waits for response)
+await light.set_extended_color_zones(0, colors)
+
+# Fast mode for animations (fire-and-forget, no response waiting)
+for frame in animation_frames:
+    await light.set_extended_color_zones(0, frame, fast=True)
+    await asyncio.sleep(0.033)  # ~30 FPS
+```
+
+**Note:** `MatrixLight.set64()` is already fire-and-forget by default.
+
 ### Packet Flow
 
 1. Create packet instance (e.g., `LightSetColor`)

{lifx_async-4.6.1 → lifx_async-4.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lifx-async
-Version: 4.6.1
+Version: 4.7.0
 Summary: A modern, type-safe, async Python library for controlling LIFX lights
 Author-email: Avi Miller <me@dje.li>
 Maintainer-email: Avi Miller <me@dje.li>

{lifx_async-4.6.1 → lifx_async-4.7.0}/docs/changelog.md

@@ -2,6 +2,14 @@
 
 <!-- version list -->
 
+## v4.7.0 (2025-12-13)
+
+### Features
+
+- **devices**: Add fast parameter to set_extended_color_zones()
+  ([`0276fca`](https://github.com/Djelibeybi/lifx-async/commit/0276fca9b18e9f78441c843880ef52b4c79dac7b))
+
+
 ## v4.6.1 (2025-12-12)
 
 ### Bug Fixes

{lifx_async-4.6.1 → lifx_async-4.7.0}/docs/user-guide/advanced-usage.md

@@ -479,6 +479,49 @@ async def with_reuse():
         # Connection closed once at end
 ```
 
+### Fire-and-Forget Mode for High-Frequency Animations
+
+For animations sending more than 20 updates per second, waiting for device acknowledgement creates unacceptable latency. Use the `fast=True` parameter to enable fire-and-forget mode:
+
+```python
+import asyncio
+from lifx import MultiZoneLight, HSBK
+
+async def rainbow_animation():
+    async with await MultiZoneLight.from_ip("192.168.1.100") as light:
+        zone_count = await light.get_zone_count()
+
+        # Animation loop at ~30 FPS
+        offset = 0
+        while True:
+            # Generate rainbow colors
+            colors = [
+                HSBK(hue=(i * 360 / zone_count + offset) % 360,
+                     saturation=1.0, brightness=1.0, kelvin=3500)
+                for i in range(zone_count)
+            ]
+
+            # Fire-and-forget: no waiting for response
+            await light.set_extended_color_zones(0, colors, fast=True)
+
+            offset = (offset + 5) % 360
+            await asyncio.sleep(0.033)  # ~30 FPS
+```
+
+**When to use `fast=True`:**
+
+- High-frequency animations (>20 updates/second)
+- Real-time visualizations (music sync, games)
+- Smooth color transitions requiring rapid updates
+
+**Trade-offs:**
+
+- No confirmation that the device received or applied the colors
+- No error detection (timeouts, unsupported commands)
+- Best for visual effects where occasional dropped frames are acceptable
+
+**Note:** `MatrixLight.set64()` is already fire-and-forget by default, making it ideal for tile animations without any additional parameters.
+
 ## Next Steps
 
 - [Troubleshooting Guide](troubleshooting.md) - Common issues and solutions

{lifx_async-4.6.1 → lifx_async-4.7.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "lifx-async"
-version = "4.6.1"
+version = "4.7.0"
 description = "A modern, type-safe, async Python library for controlling LIFX lights"
 readme = "README.md"
 requires-python = ">=3.11"

{lifx_async-4.6.1 → lifx_async-4.7.0}/src/lifx/devices/multizone.py

@@ -604,6 +604,8 @@ class MultiZoneLight(Light):
         colors: list[HSBK],
         duration: float = 0.0,
         apply: ExtendedAppReq = ExtendedAppReq.APPLY,
+        *,
+        fast: bool = False,
     ) -> None:
         """Set colors for multiple zones efficiently (up to 82 zones per call).
 
@@ -615,12 +617,15 @@ class MultiZoneLight(Light):
             colors: List of HSBK colors to set (max 82)
             duration: Transition duration in seconds (default 0.0)
             apply: Application mode (default APPLY)
+            fast: If True, send fire-and-forget without waiting for response.
+                  Use for high-frequency animations (>20 updates/second).
 
         Raises:
             ValueError: If colors list is too long or zone index is invalid
             LifxDeviceNotFoundError: If device is not connected
-            LifxTimeoutError: If device does not respond
+            LifxTimeoutError: If device does not respond (only when fast=False)
             LifxUnsupportedCommandError: If device doesn't support this command
+                (only when fast=False)
 
         Example:
             ```python
@@ -630,6 +635,11 @@ class MultiZoneLight(Light):
                 for i in range(10)
             ]
             await light.set_extended_color_zones(0, colors)
+
+            # High-speed animation loop
+            for frame in animation_frames:
+                await light.set_extended_color_zones(0, frame, fast=True)
+                await asyncio.sleep(0.033)  # ~30 FPS
             ```
         """
         if zone_index < 0:
@@ -637,7 +647,9 @@ class MultiZoneLight(Light):
         if len(colors) > 82:
             raise ValueError(f"Too many colors: {len(colors)} (max 82 per request)")
         if len(colors) == 0:
-            raise ValueError("Colors list cannot be empty")  # Convert to protocol HSBK
+            raise ValueError("Colors list cannot be empty")
+
+        # Convert to protocol HSBK
         protocol_colors = [color.to_protocol() for color in colors]
 
         # Pad to 82 colors if needed
@@ -647,17 +659,25 @@ class MultiZoneLight(Light):
         # Convert duration to milliseconds
         duration_ms = int(duration * 1000)
 
-        # Send request
-        result = await self.connection.request(
-            packets.MultiZone.SetExtendedColorZones(
-                duration=duration_ms,
-                apply=apply,
-                index=zone_index,
-                colors_count=len(colors),
-                colors=protocol_colors,
-            ),
+        packet = packets.MultiZone.SetExtendedColorZones(
+            duration=duration_ms,
+            apply=apply,
+            index=zone_index,
+            colors_count=len(colors),
+            colors=protocol_colors,
         )
-        self._raise_if_unhandled(result)
+
+        if fast:
+            # Fire-and-forget: no ack, no response, no waiting
+            await self.connection.send_packet(
+                packet,
+                ack_required=False,
+                res_required=False,
+            )
+        else:
+            # Standard: wait for response and check for errors
+            result = await self.connection.request(packet)
+            self._raise_if_unhandled(result)
 
         _LOGGER.debug(
             {
@@ -678,6 +698,7 @@ class MultiZoneLight(Light):
                     ],
                     "duration": duration_ms,
                     "apply": apply.name,
+                    "fast": fast,
                 },
             }
         )

{lifx_async-4.6.1 → lifx_async-4.7.0}/tests/test_devices/test_multizone.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 from collections.abc import AsyncIterator
+from unittest.mock import AsyncMock
 
 import pytest
 
@@ -429,6 +430,43 @@ class TestMultiZoneLight:
         with pytest.raises(ValueError, match="Too many colors"):
             await multizone_light.set_extended_color_zones(0, colors)
 
+    async def test_set_extended_color_zones_fast_mode(
+        self, multizone_light: MultiZoneLight
+    ) -> None:
+        """Test setting extended color zones in fast (fire-and-forget) mode."""
+        # Pre-populate zone count to avoid internal get_zone_count() calls
+        multizone_light._zone_count = 82
+
+        # Set up send_packet as AsyncMock for fire-and-forget mode
+        multizone_light.connection.send_packet = AsyncMock()
+
+        # Create list of colors
+        colors = [
+            HSBK(hue=i * 36, saturation=1.0, brightness=1.0, kelvin=3500)
+            for i in range(10)
+        ]
+        await multizone_light.set_extended_color_zones(
+            0, colors, duration=0.5, fast=True
+        )
+
+        # Verify send_packet was called (not request)
+        multizone_light.connection.send_packet.assert_called_once()
+        multizone_light.connection.request.assert_not_called()
+
+        # Get the send_packet call
+        call_args = multizone_light.connection.send_packet.call_args
+
+        # Verify packet has correct values
+        packet = call_args[0][0]
+        assert packet.index == 0
+        assert packet.colors_count == 10
+        assert packet.duration == 500  # 0.5 seconds in ms
+        assert len(packet.colors) == 82  # Padded to 82
+
+        # Verify fire-and-forget flags
+        assert call_args[1]["ack_required"] is False
+        assert call_args[1]["res_required"] is False
+
 
 class TestMultiZoneEffect:
     """Tests for MultiZoneEffect class."""

{lifx_async-4.6.1 → lifx_async-4.7.0}/uv.lock

@@ -337,7 +337,7 @@ wheels = [
 
 [[package]]
 name = "lifx-async"
-version = "4.6.1"
+version = "4.7.0"
 source = { editable = "." }
 
 [package.dev-dependencies]