lifx-async 4.3.8__tar.gz → 4.4.0__tar.gz

{lifx_async-4.3.8 → lifx_async-4.4.0}/.github/workflows/ci.yml

@@ -35,7 +35,7 @@ jobs:
     - uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3 # v6
 
     - name: Set up Python
-      uses: actions/setup-python@e797f83bcb11b83ae66e0230d6156d7c80228e7c # v6
+      uses: actions/setup-python@83679a892e2d95755f2dac6acb0bfd1e9ac5d548 # v6
       with:
         python-version: ${{ env.PYTHON_VERSION }}
 
@@ -59,8 +59,8 @@ jobs:
 
     - name: Check for security issues
       run: |
-        uv pip install bandit
-        uv run bandit -r src/
+        uv pip install "bandit[toml]"
+        uv run bandit -c pyproject.toml -r src/
 
   # Testing matrix across Python versions and platforms
   test:
@@ -77,7 +77,7 @@ jobs:
     - uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3 # v6
 
     - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@e797f83bcb11b83ae66e0230d6156d7c80228e7c # v6
+      uses: actions/setup-python@83679a892e2d95755f2dac6acb0bfd1e9ac5d548 # v6
       with:
         python-version: ${{ matrix.python-version }}
 
@@ -95,6 +95,7 @@ jobs:
       run: uv run --frozen pytest
 
     - name: Upload coverage to Codecov
+      if: matrix.os == 'ubuntu-latest'
       uses: codecov/codecov-action@5a1091511ad55cbe89839c7260b706298ca349f7 # v5
       with:
         env_vars: OS,PYTHON
@@ -105,6 +106,7 @@ jobs:
         verbose: true
 
     - name: Upload test results to Codecov
+      if: matrix.os == 'ubuntu-latest'
       uses: codecov/codecov-action@5a1091511ad55cbe89839c7260b706298ca349f7 # v5
       with:
         env_vars: OS,PYTHON
@@ -127,7 +129,7 @@ jobs:
     - uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3   # v6
 
     - name: Set up Python
-      uses: actions/setup-python@e797f83bcb11b83ae66e0230d6156d7c80228e7c   # v6
+      uses: actions/setup-python@83679a892e2d95755f2dac6acb0bfd1e9ac5d548   # v6
       with:
         python-version: ${{ env.PYTHON_VERSION }}
 
@@ -191,7 +193,7 @@ jobs:
         ssh-key: ${{ secrets.DEPLOY_KEY }}
 
     - name: Set up Python
-      uses: actions/setup-python@e797f83bcb11b83ae66e0230d6156d7c80228e7c # v6
+      uses: actions/setup-python@83679a892e2d95755f2dac6acb0bfd1e9ac5d548 # v6
       with:
         python-version: ${{ env.PYTHON_VERSION }}
 

{lifx_async-4.3.8 → lifx_async-4.4.0}/.github/workflows/docs.yml

@@ -30,7 +30,7 @@ jobs:
         fetch-depth: 0    # Fetch all history for git-revision-date-localized
 
     - name: Set up Python
-      uses: actions/setup-python@e797f83bcb11b83ae66e0230d6156d7c80228e7c # v6
+      uses: actions/setup-python@83679a892e2d95755f2dac6acb0bfd1e9ac5d548 # v6
       with:
         python-version: ${{ env.PYTHON_VERSION }}
 
@@ -64,7 +64,7 @@ jobs:
         fetch-depth: 0
 
     - name: Set up Python
-      uses: actions/setup-python@e797f83bcb11b83ae66e0230d6156d7c80228e7c # v6
+      uses: actions/setup-python@83679a892e2d95755f2dac6acb0bfd1e9ac5d548 # v6
       with:
         python-version: ${{ env.PYTHON_VERSION }}
 
@@ -92,7 +92,7 @@ jobs:
     - uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3 # v6
 
     - name: Set up Python
-      uses: actions/setup-python@e797f83bcb11b83ae66e0230d6156d7c80228e7c # v6
+      uses: actions/setup-python@83679a892e2d95755f2dac6acb0bfd1e9ac5d548 # v6
       with:
         python-version: ${{ env.PYTHON_VERSION }}
 

{lifx_async-4.3.8 → lifx_async-4.4.0}/CLAUDE.md

@@ -12,7 +12,7 @@ structures from a YAML specification.
 **Python Versions**: 3.11, 3.12, 3.13, 3.14 (tested on all versions via CI)
 **Runtime Dependencies**: Zero - completely dependency-free!
 **Async Framework**: Python's built-in `asyncio` (no external async library required)
-**Test Isolation**: lifx-emulator runs as subprocess, not a dependency
+**Test Isolation**: lifx-emulator-core runs embedded in-process for fast, cross-platform testing
 
 ## Essential Commands
 
@@ -610,38 +610,27 @@ The `discover_devices()` function implements DoS protection through:
 Test files mirror source structure: `tests/test_devices/test_light.py` tests
 `src/lifx/devices/light.py`
 
-### Integration Tests with lifx-emulator
+### Integration Tests with lifx-emulator-core
 
-Some tests require the `lifx-emulator` to run integration tests against real protocol implementations.
-The emulator runs as a **separate subprocess** and is **not** a dependency of lifx.
+Some tests require `lifx-emulator-core` to run integration tests against real protocol implementations.
+The emulator runs **embedded in-process** as a dev dependency, providing:
+- Fast startup (~5-10ms vs 500ms+ for subprocess)
+- Cross-platform support (Windows, macOS, Linux)
+- Direct access to emulator internals for scenario testing
 
-**Setup Options**:
-
-1. **Development setup** (recommended): Clone lifx-emulator as a sibling directory
-   ```bash
-   cd ..
-   git clone https://github.com/Djelibeybi/lifx-emulator.git
-   cd lifx-emulator
-   uv sync
-   cd ../lifx
-   ```
-
-2. **System install**: Install lifx-emulator globally (requires Python 3.13+)
-   ```bash
-   uv tool install lifx-emulator
-   ```
+**Setup**: The emulator is automatically installed as a dev dependency:
+```bash
+uv sync  # Installs lifx-emulator-core automatically
+```
 
 **Running Integration Tests**:
+- Tests marked with `@pytest.mark.emulator` use the embedded emulator
 - If emulator is not available, these tests are automatically skipped
-- No code changes needed - pytest plugin handles everything
-- **Works on all Python versions (3.11+)** since emulator runs as separate process
-
-**Note**: The emulator itself requires Python 3.13+, but it runs as a subprocess so your
-lifx tests can run on any supported Python version (3.11-3.14).
+- **Works on all Python versions (3.11+)**
 
 **External Emulator Management**:
 
-For cases where you want to manage the emulator separately (or test against actual hardware), you can skip the automatic emulator subprocess startup:
+For cases where you want to manage the emulator separately (or test against actual hardware):
 
 ```bash
 # Use an externally managed emulator instance
@@ -654,7 +643,6 @@ LIFX_EMULATOR_EXTERNAL=1 pytest
 This is useful when:
 - Testing against actual LIFX hardware on your network
 - Running the emulator with custom configuration or device setup
-- Using a shared emulator instance across multiple test runs
 - Debugging emulator behavior separately from the test suite
 
 **Key Test Files:**
@@ -801,3 +789,4 @@ Critical constants are defined in `src/lifx/const.py`:
 - Button/Relay/Switch devices are explicitly out of scope (library focuses on lighting devices)
 - Not yet published to PyPI
 - Never update docs/changelog.md manually as it is auto-generated during the release process by the CI/CD workflow.
+- If a field is user-visible, it must never be bytes. This means things like serial, label, location and group must always be converted to a string prior to storing it anywhere a user would be able to access it. Conversion to and from bytes should happen either as close to sending or receiving the packet as possible.

{lifx_async-4.3.8 → lifx_async-4.4.0}/PKG-INFO

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

@@ -2,6 +2,22 @@
 
 <!-- version list -->
 
+## v4.4.0 (2025-11-29)
+
+### Features
+
+- **devices**: Add factory pattern with automatic type detection and state management
+  ([`4374248`](https://github.com/Djelibeybi/lifx-async/commit/4374248bb46cb5af1cf303866ad82b6692bb8932))
+
+
+## v4.3.9 (2025-11-27)
+
+### Bug Fixes
+
+- **network**: Propagate timeout from request() to internal methods
+  ([`b35ebea`](https://github.com/Djelibeybi/lifx-async/commit/b35ebea46120bfd4ad9ce149f5e25125d3694b30))
+
+
 ## v4.3.8 (2025-11-25)
 
 ### Bug Fixes

{lifx_async-4.3.8 → lifx_async-4.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "lifx-async"
-version = "4.3.8"
+version = "4.4.0"
 description = "A modern, type-safe, async Python library for controlling LIFX lights"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -31,7 +31,7 @@ classifiers = [
 [dependency-groups]
 dev = [
     "hatchling>=1.27.0",
-    "lifx-emulator>=2.4.0",
+    "lifx-emulator-core>=3.0.3",
     "mkdocs-git-revision-date-localized-plugin>=1.4.7",
     "mkdocs-llmstxt>=0.4.0",
     "mkdocs-material>=9.6.22",
@@ -41,7 +41,6 @@ dev = [
     "pytest-asyncio>=0.24.0",
     "pytest-cov>=7.0.0",
     "pytest-sugar>=1.1.1",
-    "pytest-xprocess>=1.0.2",
     "pyyaml>=6.0.3",
     "ruff>=0.14.2",
 ]
@@ -73,7 +72,6 @@ ignore = []
 "src/lifx/protocol/packets.py" = ["E501"]
 "src/lifx/products/registry.py" = ["E501"]
 
-
 [tool.pyright]
 typeCheckingMode = "standard"
 pythonVersion = "3.11"
@@ -84,6 +82,9 @@ exclude = [
     "**/registry.py",   # Auto-generated from products.json
 ]
 
+[tool.bandit]
+skips = ["B101"]
+
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 pythonpath = ["src"]
@@ -102,6 +103,9 @@ addopts = """\
     """
 asyncio_mode = "auto"
 asyncio_default_fixture_loop_scope = "function"
+markers = [
+    "emulator: tests that require the lifx-emulator-core embedded emulator",
+]
 
 [tool.coverage.run]
 omit = [

{lifx_async-4.3.8 → lifx_async-4.4.0}/src/lifx/__init__.py

@@ -21,12 +21,17 @@ from lifx.devices import (
     DeviceVersion,
     FirmwareInfo,
     HevLight,
+    HevLightState,
     InfraredLight,
+    InfraredLightState,
     Light,
+    LightState,
     MatrixEffect,
     MatrixLight,
+    MatrixLightState,
     MultiZoneEffect,
     MultiZoneLight,
+    MultiZoneLightState,
     TileInfo,
     WifiInfo,
 )
@@ -57,10 +62,15 @@ __all__ = [
     # Core classes
     "Device",
     "Light",
+    "LightState",
     "HevLight",
+    "HevLightState",
     "InfraredLight",
+    "InfraredLightState",
     "MultiZoneLight",
+    "MultiZoneLightState",
     "MatrixLight",
+    "MatrixLightState",
     # Color
     "HSBK",
     "Colors",

{lifx_async-4.3.8 → lifx_async-4.4.0}/src/lifx/api.py

@@ -10,7 +10,6 @@ This module provides simplified interfaces for common operations:
 from __future__ import annotations
 
 import asyncio
-import logging
 from collections import defaultdict
 from collections.abc import AsyncGenerator, Iterator, Sequence
 from dataclasses import dataclass
@@ -27,12 +26,11 @@ from lifx.const import (
     MAX_RESPONSE_TIME,
 )
 from lifx.devices import (
+    CollectionInfo,
     Device,
-    GroupInfo,
     HevLight,
     InfraredLight,
     Light,
-    LocationInfo,
     MatrixLight,
     MultiZoneLight,
 )
@@ -44,14 +42,12 @@ from lifx.network.discovery import (
 from lifx.protocol import packets
 from lifx.theme import Theme
 
-_LOGGER = logging.getLogger(__name__)
-
 
 @dataclass
 class LocationGrouping:
     """Organizational structure for location-based grouping."""
 
-    uuid: bytes
+    uuid: str
     label: str
     devices: list[Device]
     updated_at: int  # Most recent updated_at from all devices
@@ -65,7 +61,7 @@ class LocationGrouping:
 class GroupGrouping:
     """Organizational structure for group-based grouping."""
 
-    uuid: bytes
+    uuid: str
     label: str
     devices: list[Device]
     updated_at: int
@@ -117,8 +113,8 @@ class DeviceGroup:
         self._matrix_lights = [light for light in devices if type(light) is MatrixLight]
         self._locations_cache: dict[str, DeviceGroup] | None = None
         self._groups_cache: dict[str, DeviceGroup] | None = None
-        self._location_metadata: dict[bytes, LocationGrouping] | None = None
-        self._group_metadata: dict[bytes, GroupGrouping] | None = None
+        self._location_metadata: dict[str, LocationGrouping] | None = None
+        self._group_metadata: dict[str, GroupGrouping] | None = None
 
     async def __aenter__(self) -> DeviceGroup:
         """Enter async context manager."""
@@ -278,17 +274,17 @@ class DeviceGroup:
         Skips devices with empty UUID (b'\\x00' * 16).
         Logs warnings for failed queries but continues gracefully.
         """
-        location_data: dict[bytes, list[tuple[Device, LocationInfo]]] = defaultdict(
+        location_data: dict[str, list[tuple[Device, CollectionInfo]]] = defaultdict(
             list
         )
 
         # Fetch all location info concurrently
-        tasks: dict[str, asyncio.Task[LocationInfo | None]] = {}
+        tasks: dict[str, asyncio.Task[CollectionInfo | None]] = {}
         async with asyncio.TaskGroup() as tg:
             for device in self._devices:
                 tasks[device.serial] = tg.create_task(device.get_location())
 
-        results: list[tuple[Device, LocationInfo | None]] = []
+        results: list[tuple[Device, CollectionInfo | None]] = []
         for device in self._devices:
             results.append((device, tasks[device.serial].result()))
 
@@ -298,10 +294,10 @@ class DeviceGroup:
                 continue
 
             # Skip empty UUIDs (unassigned)
-            if location_info.location == b"\x00" * 16:
+            if location_info.uuid == "0000000000000000":
                 continue
 
-            location_data[location_info.location].append((device, location_info))
+            location_data[location_info.uuid].append((device, location_info))
 
         # Build metadata dictionary with conflict resolution
         self._location_metadata = {}
@@ -333,15 +329,15 @@ class DeviceGroup:
         Logs warnings for failed queries but continues gracefully.
         """
         # Collect group info from all devices concurrently
-        group_data: dict[bytes, list[tuple[Device, GroupInfo]]] = defaultdict(list)
+        group_data: dict[str, list[tuple[Device, CollectionInfo]]] = defaultdict(list)
 
-        tasks: dict[str, asyncio.Task[GroupInfo | None]] = {}
+        tasks: dict[str, asyncio.Task[CollectionInfo | None]] = {}
         async with asyncio.TaskGroup() as tg:
             for device in self._devices:
                 tasks[device.serial] = tg.create_task(device.get_group())
 
         # Fetch all group info concurrently
-        results: list[tuple[Device, GroupInfo | None]] = []
+        results: list[tuple[Device, CollectionInfo | None]] = []
         for device in self._devices:
             results.append((device, tasks[device.serial].result()))
 
@@ -351,10 +347,10 @@ class DeviceGroup:
                 continue
 
             # Skip empty UUIDs (unassigned)
-            if group_info.group == b"\x00" * 16:
+            if group_info.uuid == "0000000000000000":
                 continue
 
-            group_data[group_info.group].append((device, group_info))
+            group_data[group_info.uuid].append((device, group_info))
 
         # Build metadata dictionary with conflict resolution
         self._group_metadata = {}
@@ -397,7 +393,7 @@ class DeviceGroup:
             )
 
         result: dict[str, DeviceGroup] = {}
-        label_uuids: dict[str, bytes] = {}
+        label_uuids: dict[str, str] = {}
 
         for location_uuid, grouping in self._location_metadata.items():
             label = grouping.label
@@ -405,7 +401,7 @@ class DeviceGroup:
             # Handle naming conflicts: if two different UUIDs have the same label,
             # append UUID suffix
             if label in label_uuids and label_uuids[label] != location_uuid:
-                label = f"{label} ({location_uuid.hex()[:8]})"
+                label = f"{label} ({location_uuid[:8]})"
 
             label_uuids[label] = location_uuid
             result[label] = DeviceGroup(grouping.devices)
@@ -436,7 +432,7 @@ class DeviceGroup:
             )
 
         result: dict[str, DeviceGroup] = {}
-        label_uuids: dict[str, bytes] = {}
+        label_uuids: dict[str, str] = {}
 
         for group_uuid, grouping in self._group_metadata.items():
             label = grouping.label
@@ -444,7 +440,7 @@ class DeviceGroup:
             # Handle naming conflicts: if two different UUIDs have the same label,
             # append UUID suffix
             if label in label_uuids and label_uuids[label] != group_uuid:
-                label = f"{label} ({group_uuid.hex()[:8]})"
+                label = f"{label} ({group_uuid[:8]})"
 
             label_uuids[label] = group_uuid
             result[label] = DeviceGroup(grouping.devices)

{lifx_async-4.3.8 → lifx_async-4.4.0}/src/lifx/const.py

@@ -32,7 +32,8 @@ MAX_RESPONSE_TIME: Final[float] = 1.0  # 1 second
 IDLE_TIMEOUT_MULTIPLIER: Final[float] = 4.0  # 4 seconds (1.0 x 4.0)
 
 # Default timeout for device requests in seconds
-DEFAULT_REQUEST_TIMEOUT: Final[float] = 8.0
+DEFAULT_REQUEST_TIMEOUT: Final[float] = 16.0
+STATE_REFRESH_DEBOUNCE_MS: Final[int] = 300
 
 # Default maximum number of retry attempts for failed requests
 DEFAULT_MAX_RETRIES: Final[int] = 8

{lifx_async-4.3.8 → lifx_async-4.4.0}/src/lifx/devices/__init__.py

@@ -3,34 +3,37 @@
 from __future__ import annotations
 
 from lifx.devices.base import (
+    CollectionInfo,
     Device,
     DeviceInfo,
     DeviceVersion,
     FirmwareInfo,
-    GroupInfo,
-    LocationInfo,
     WifiInfo,
 )
-from lifx.devices.hev import HevLight
-from lifx.devices.infrared import InfraredLight
-from lifx.devices.light import Light
-from lifx.devices.matrix import MatrixEffect, MatrixLight, TileInfo
-from lifx.devices.multizone import MultiZoneEffect, MultiZoneLight
+from lifx.devices.hev import HevLight, HevLightState
+from lifx.devices.infrared import InfraredLight, InfraredLightState
+from lifx.devices.light import Light, LightState
+from lifx.devices.matrix import MatrixEffect, MatrixLight, MatrixLightState, TileInfo
+from lifx.devices.multizone import MultiZoneEffect, MultiZoneLight, MultiZoneLightState
 
 __all__ = [
+    "CollectionInfo",
     "Device",
     "DeviceInfo",
     "DeviceVersion",
     "FirmwareInfo",
-    "GroupInfo",
     "HevLight",
+    "HevLightState",
     "InfraredLight",
+    "InfraredLightState",
     "Light",
-    "LocationInfo",
+    "LightState",
     "MatrixEffect",
     "MatrixLight",
+    "MatrixLightState",
     "MultiZoneEffect",
     "MultiZoneLight",
+    "MultiZoneLightState",
     "TileInfo",
     "WifiInfo",
 ]