lifx-async 4.3.4__tar.gz → 4.3.6__tar.gz

{lifx_async-4.3.4 → lifx_async-4.3.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lifx-async
-Version: 4.3.4
+Version: 4.3.6
 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.3.4 → lifx_async-4.3.6}/docs/changelog.md

@@ -2,6 +2,22 @@
 
 <!-- version list -->
 
+## v4.3.6 (2025-11-25)
+
+### Bug Fixes
+
+- **network**: Return StateUnhandled packets instead of raising exception
+  ([`f27e848`](https://github.com/Djelibeybi/lifx-async/commit/f27e84849656a84e7e120d66d1dba7bbabe18ed5))
+
+
+## v4.3.5 (2025-11-22)
+
+### Bug Fixes
+
+- **devices**: Allow MatrixEffect without palette
+  ([`fb31df5`](https://github.com/Djelibeybi/lifx-async/commit/fb31df51b1af9d8c7c2f573ec9619566b4f7393b))
+
+
 ## v4.3.4 (2025-11-22)
 
 ### Bug Fixes

{lifx_async-4.3.4 → lifx_async-4.3.6}/pyproject.toml

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

{lifx_async-4.3.4 → lifx_async-4.3.6}/src/lifx/devices/matrix.py

@@ -171,11 +171,6 @@ class MatrixEffect:
 
     def __post_init__(self) -> None:
         """Initialize defaults and validate fields."""
-        # Initialize default palette if not provided
-        if self.palette is None:
-            # Default palette: single white color
-            self.palette = [HSBK(0, 0, 1.0, 3500)]
-
         # Validate all fields
         # Speed can be 0 only when effect is OFF
         if self.effect_type != FirmwareEffect.OFF:
@@ -184,7 +179,11 @@ class MatrixEffect:
             raise ValueError(f"Effect speed must be non-negative, got {self.speed}")
 
         self._validate_duration(self.duration)
-        self._validate_palette(self.palette)
+
+        # Only validate palette if provided
+        if self.palette is not None:
+            self._validate_palette(self.palette)
+
         self._validate_saturation(self.cloud_saturation_min, "cloud_saturation_min")
         self._validate_saturation(self.cloud_saturation_max, "cloud_saturation_max")
 
@@ -762,7 +761,7 @@ class MatrixLight(Light):
             effect_type: Type of effect (OFF, MORPH, FLAME, SKY)
             speed: Effect speed in seconds (default: 3)
             duration: Total effect duration in nanoseconds (0 for infinite)
-            palette: Color palette for the effect (max 16 colors)
+            palette: Color palette for the effect (max 16 colors, None for no palette)
             sky_type: Sky effect type (SUNRISE, SUNSET, CLOUDS)
             cloud_saturation_min: Minimum cloud saturation (0-255, for CLOUDS)
             cloud_saturation_max: Maximum cloud saturation (0-255, for CLOUDS)
@@ -780,6 +779,12 @@ class MatrixLight(Light):
             ...     speed=5.0,
             ...     palette=rainbow,
             ... )
+
+            >>> # Set effect without a palette
+            >>> await matrix.set_effect(
+            ...     effect_type=FirmwareEffect.FLAME,
+            ...     speed=3.0,
+            ... )
         """
         _LOGGER.debug(
             "Setting matrix effect %s (speed=%d) for %s",
@@ -801,20 +806,22 @@ class MatrixLight(Light):
         )
 
         # Convert to protocol format
-        # Note: palette is guaranteed to be non-None by MatrixEffect.__post_init__
-        palette = effect.palette if effect.palette is not None else []
         proto_palette = []
-        for color in palette:
-            proto_palette.append(
-                LightHsbk(
-                    hue=int(color.hue / 360 * 65535),
-                    saturation=int(color.saturation * 65535),
-                    brightness=int(color.brightness * 65535),
-                    kelvin=color.kelvin,
+        palette_count = 0
+
+        if effect.palette is not None:
+            palette_count = len(effect.palette)
+            for color in effect.palette:
+                proto_palette.append(
+                    LightHsbk(
+                        hue=int(color.hue / 360 * 65535),
+                        saturation=int(color.saturation * 65535),
+                        brightness=int(color.brightness * 65535),
+                        kelvin=color.kelvin,
+                    )
                 )
-            )
 
-        # Pad palette to 16 colors
+        # Pad palette to 16 colors (protocol requirement)
         while len(proto_palette) < 16:
             proto_palette.append(LightHsbk(0, 0, 0, 3500))
 
@@ -828,7 +835,7 @@ class MatrixLight(Light):
                 cloud_saturation_min=effect.cloud_saturation_min,
                 cloud_saturation_max=effect.cloud_saturation_max,
             ),
-            palette_count=len(palette),
+            palette_count=palette_count,
             palette=proto_palette,
         )
 

{lifx_async-4.3.4 → lifx_async-4.3.6}/src/lifx/network/connection.py

@@ -22,7 +22,6 @@ from lifx.exceptions import (
     LifxConnectionError,
     LifxProtocolError,
     LifxTimeoutError,
-    LifxUnsupportedCommandError,
 )
 from lifx.network.message import create_message, parse_message
 from lifx.network.transport import UdpTransport
@@ -443,13 +442,12 @@ class DeviceConnection:
             LifxConnectionError: If connection is not open
             LifxProtocolError: If response correlation validation fails
             LifxTimeoutError: If no response after all retries
-            LifxUnsupportedCommandError: If device doesn't support command
         """
         if not self._is_open or self._transport is None:
-            raise LifxConnectionError("Connection not open")
+            raise LifxConnectionError("Connection not open")  # pragma: no cover
 
         if timeout is None:
-            timeout = self.timeout
+            timeout = self.timeout  # pragma: no cover
 
         if max_retries is None:
             max_retries = self.max_retries
@@ -597,12 +595,6 @@ class DeviceConnection:
                                 f"got {header.sequence}, max expected {max_expected}"
                             )
 
-                        # Check for StateUnhandled
-                        if header.pkt_type == _STATE_UNHANDLED_PKT_TYPE:
-                            raise LifxUnsupportedCommandError(
-                                "Request unsupported by device: received StateUnhandled"
-                            )
-
                         # Yield response (can be from any retry attempt)
                         has_yielded = True
                         last_response_time = time.monotonic()
@@ -640,7 +632,7 @@ class DeviceConnection:
         request: Any,
         timeout: float | None = None,
         max_retries: int | None = None,
-    ) -> AsyncGenerator[None, None]:
+    ) -> AsyncGenerator[bool, None]:
         """Internal implementation of request_ack_stream with retry logic.
 
         This is an async generator that sends a request requiring acknowledgement
@@ -652,18 +644,17 @@ class DeviceConnection:
             max_retries: Maximum retries
 
         Yields:
-            None (single yield on successful ack)
+            True for successful ACK, False if device returned StateUnhandled
 
         Raises:
             LifxConnectionError: If connection is not open
             LifxTimeoutError: If no ack after all retries
-            LifxUnsupportedCommandError: If device doesn't support command
         """
         if not self._is_open or self._transport is None:
-            raise LifxConnectionError("Connection not open")
+            raise LifxConnectionError("Connection not open")  # pragma: no cover
 
         if timeout is None:
-            timeout = self.timeout
+            timeout = self.timeout  # pragma: no cover
 
         if max_retries is None:
             max_retries = self.max_retries
@@ -729,14 +720,13 @@ class DeviceConnection:
                         f"{Serial.from_protocol(header.target).to_string()})"
                     )
 
-                # Check for StateUnhandled
+                # Check for StateUnhandled - return False to indicate unsupported
                 if header.pkt_type == _STATE_UNHANDLED_PKT_TYPE:
-                    raise LifxUnsupportedCommandError(
-                        "Request unsupported by device: received StateUnhandled"
-                    )
+                    yield False
+                    return
 
                 # ACK received successfully
-                yield
+                yield True
                 return
 
             except TimeoutError as e:
@@ -791,14 +781,14 @@ class DeviceConnection:
             timeout: Request timeout in seconds
 
         Yields:
-            Unpacked response packet instances
-            For SET packets: yields True once (acknowledgement)
+            Unpacked response packet instances (including StateUnhandled if device
+            doesn't support the command)
+            For SET packets: yields True (acknowledgement) or False (StateUnhandled)
 
         Raises:
             LifxTimeoutError: If request times out
             LifxProtocolError: If response invalid
             LifxConnectionError: If connection fails
-            LifxUnsupportedCommandError: If command not supported
 
         Example:
             ```python
@@ -808,11 +798,16 @@ class DeviceConnection:
                 label = state.label  # Already decoded to string
                 break
 
-            # SET request yields True (acknowledgement)
-            async for _ in conn.request_stream(
+            # SET request yields True (acknowledgement) or False (StateUnhandled)
+            async for result in conn.request_stream(
                 packets.Light.SetColor(color=hsbk, duration=1000)
             ):
-                # Acknowledgement received
+                if result:
+                    # Acknowledgement received
+                    pass
+                else:
+                    # Device doesn't support this command
+                    pass
                 break
 
             # Multi-response GET - stream all responses
@@ -875,9 +870,12 @@ class DeviceConnection:
 
         elif packet_kind == "SET":
             # Request acknowledgement
-            async for _ in self._request_ack_stream_impl(packet, timeout=timeout):
+            async for ack_result in self._request_ack_stream_impl(
+                packet, timeout=timeout
+            ):
                 # Log the request/ack cycle
                 request_values = packet.as_dict
+                reply_packet = "Acknowledgement" if ack_result else "StateUnhandled"
                 _LOGGER.debug(
                     {
                         "class": "DeviceConnection",
@@ -887,7 +885,7 @@ class DeviceConnection:
                             "values": request_values,
                         },
                         "reply": {
-                            "packet": "Acknowledgement",
+                            "packet": reply_packet,
                             "values": {},
                         },
                         "serial": self.serial,
@@ -895,7 +893,7 @@ class DeviceConnection:
                     }
                 )
 
-                yield True
+                yield ack_result
                 return
 
         else:
@@ -934,7 +932,7 @@ class DeviceConnection:
                         yield response_packet
                         return
                 else:
-                    raise LifxUnsupportedCommandError(
+                    raise LifxProtocolError(
                         f"Cannot auto-handle packet kind: {packet_kind}"
                     )
             else:
@@ -961,14 +959,14 @@ class DeviceConnection:
             timeout: Request timeout in seconds
 
         Returns:
-            Single unpacked response packet
-            True for SET acknowledgement
+            Single unpacked response packet (including StateUnhandled if device
+            doesn't support the command)
+            For SET packets: True (acknowledgement) or False (StateUnhandled)
 
         Raises:
             LifxTimeoutError: If no response within timeout
             LifxProtocolError: If response invalid
             LifxConnectionError: If connection fails
-            LifxUnsupportedCommandError: If command not supported
 
         Example:
             ```python
@@ -977,10 +975,13 @@ class DeviceConnection:
             color = HSBK.from_protocol(state.color)
             label = state.label  # Already decoded to string
 
-            # SET request returns True
+            # SET request returns True or False
             success = await conn.request(
                 packets.Light.SetColor(color=hsbk, duration=1000)
             )
+            if not success:
+                # Device doesn't support this command (returned StateUnhandled)
+                pass
             ```
         """
         async for response in self.request_stream(packet, timeout):

{lifx_async-4.3.4 → lifx_async-4.3.6}/tests/conftest.py

@@ -272,6 +272,62 @@ def ceiling_device(emulator_server: int, emulator_api_url: str):
             pass  # Best effort cleanup
 
 
+@pytest.fixture(scope="session")
+def switch_device(emulator_server: int, emulator_api_url: str):
+    """Create a LIFX Switch device (product 70) for StateUnhandled testing.
+
+    The Switch device does not support Light commands (GetColor, SetColor, etc.)
+    and will return StateUnhandled responses. This is useful for testing that
+    the library correctly handles unsupported command responses.
+
+    Returns:
+        DeviceConnection instance for the Switch device
+    """
+    from lifx.network.connection import DeviceConnection
+
+    # Wait for API to be ready (emulator might not have HTTP API ready immediately)
+    max_retries = 10
+    for i in range(max_retries):
+        try:
+            response = requests.get(f"{emulator_api_url}/docs", timeout=1.0)
+            if response.status_code == 200:
+                break
+        except requests.exceptions.ConnectionError:
+            if i < max_retries - 1:
+                time.sleep(0.5)
+            else:
+                raise
+
+    # Create Switch device via API (product 70 = LIFX Switch)
+    response = requests.post(
+        f"{emulator_api_url}/devices",
+        json={
+            "product_id": 70,  # LIFX Switch
+            # Use serial that doesn't conflict with existing devices
+            "serial": "d073d5000200",
+        },
+        timeout=5.0,
+    )
+    response.raise_for_status()  # 201 Created is expected
+
+    try:
+        switch = DeviceConnection(
+            serial="d073d5000200",
+            ip="127.0.0.1",
+            port=emulator_server,
+        )
+        yield switch
+    finally:
+        # Clean up: delete the device
+        try:
+            requests.delete(
+                f"{emulator_api_url}/devices/d073d5000200",
+                timeout=5.0,
+            )
+        except Exception:
+            pass  # Best effort cleanup
+
+
 @pytest.fixture
 def scenario_manager(emulator_api_url: str):
     """Provide a context manager for scenario management.

{lifx_async-4.3.4 → lifx_async-4.3.6}/tests/test_devices/test_matrix.py

@@ -177,8 +177,9 @@ class TestMatrixLight:
             assert isinstance(effect.effect_type, FirmwareEffect)
             assert effect.speed >= 0
             assert effect.duration >= 0
-            assert effect.palette is not None
-            assert len(effect.palette) > 0
+            # Palette can be None if palette_count is 0
+            if effect.palette is not None:
+                assert len(effect.palette) > 0
 
     async def test_tile_effect_cached_property(self, emulator_devices) -> None:
         """Test tile_effect property caching."""
@@ -321,6 +322,21 @@ class TestMatrixLight:
             effect = await matrix.get_effect()
             assert effect.effect_type == FirmwareEffect.OFF
 
+    async def test_set_effect_without_palette(self, emulator_devices) -> None:
+        """Test setting effect without a palette (palette_count=0)."""
+        matrix = emulator_devices[6]
+        async with matrix:
+            # Set effect without palette - should send palette_count=0
+            await matrix.set_effect(
+                effect_type=FirmwareEffect.MORPH,
+                speed=3000,
+            )
+
+            # Verify effect was set
+            effect = await matrix.get_effect()
+            assert effect.effect_type == FirmwareEffect.MORPH
+            assert effect.palette is None
+
     async def test_get64_large_tile(self, ceiling_device) -> None:
         """Test getting colors from 16x8 tile (128 zones) with default parameters.
 
@@ -553,15 +569,13 @@ class TestMatrixEffect:
         assert effect.palette is not None
         assert len(effect.palette) == 1
 
-    def test_effect_default_palette(self) -> None:
-        """Test that default palette is created if not provided."""
+    def test_effect_none_palette(self) -> None:
+        """Test that palette can be None (no palette specified)."""
         effect = MatrixEffect(
             effect_type=FirmwareEffect.MORPH,
             speed=3000,
         )
-        assert effect.palette is not None
-        assert len(effect.palette) == 1
-        assert isinstance(effect.palette[0], HSBK)
+        assert effect.palette is None
 
     def test_effect_validation_negative_speed(self) -> None:
         """Test that negative speed raises error."""

{lifx_async-4.3.4 → lifx_async-4.3.6}/tests/test_network/test_connection.py

@@ -351,7 +351,7 @@ class TestDeviceConnectionRequestStream:
             as_dict: dict[str, object] = {}
 
         with patch.object(conn, "_ensure_open", return_value=None):
-            with pytest.raises(LifxUnsupportedCommandError, match="auto-handle"):
+            with pytest.raises(LifxProtocolError, match="auto-handle"):
                 async for _ in conn.request_stream(UnknownPacket()):
                     pass
 
@@ -381,8 +381,8 @@ class TestDeviceConnectionRequestStream:
         )
 
         async def mock_ack_stream_impl(packet, timeout=None, max_retries=None):
-            # Yield once to indicate ACK received
-            yield
+            # Yield True to indicate ACK received
+            yield True
 
         with (
             patch.object(conn, "_ensure_open", return_value=None),
@@ -546,3 +546,51 @@ class TestDeviceConnectionRequestStream:
 
             with pytest.raises(LifxTimeoutError, match="No response from"):
                 await conn.request(get_packet)
+
+
+class TestStateUnhandledResponses:
+    """Test StateUnhandled responses from devices that don't support commands."""
+
+    @pytest.mark.emulator
+    async def test_get_color_returns_state_unhandled_for_switch(
+        self, switch_device
+    ) -> None:
+        """Test GetColor to a Switch device returns StateUnhandled packet.
+
+        Switch devices don't support Light commands, so GetColor should
+        return a StateUnhandled packet instead of raising an exception.
+        """
+        from lifx.protocol import packets
+
+        async with switch_device:
+            # Send GetColor to a Switch - should return StateUnhandled
+            response = await switch_device.request(packets.Light.GetColor())
+
+            # Should return StateUnhandled packet, not raise an exception
+            assert isinstance(response, packets.Device.StateUnhandled)
+            # The unhandled_type field contains the packet type that wasn't handled
+            assert response.unhandled_type == packets.Light.GetColor.PKT_TYPE
+
+    @pytest.mark.emulator
+    async def test_set_color_returns_false_for_switch(self, switch_device) -> None:
+        """Test SetColor to a Switch device returns False.
+
+        Switch devices don't support Light commands, so SetColor should
+        return False (indicating StateUnhandled) instead of True (ACK).
+        """
+        from lifx.color import HSBK
+        from lifx.protocol import packets
+
+        async with switch_device:
+            # Create a SetColor packet
+            color = HSBK(hue=120, saturation=1.0, brightness=1.0, kelvin=3500)
+            set_packet = packets.Light.SetColor(
+                color=color.to_protocol(),
+                duration=0,
+            )
+
+            # Send SetColor to a Switch - should return False (StateUnhandled)
+            result = await switch_device.request(set_packet)
+
+            # Should return False, not True or raise an exception
+            assert result is False

{lifx_async-4.3.4 → lifx_async-4.3.6}/uv.lock

@@ -432,7 +432,7 @@ wheels = [
 
 [[package]]
 name = "lifx-async"
-version = "4.3.4"
+version = "4.3.6"
 source = { editable = "." }
 
 [package.dev-dependencies]