lifx-async 4.7.4__tar.gz → 4.8.0__tar.gz

{lifx_async-4.7.4 → lifx_async-4.8.0}/.github/workflows/ci.yml

@@ -40,7 +40,7 @@ jobs:
         python-version: ${{ env.PYTHON_VERSION }}
 
     - name: Install uv
-      uses: astral-sh/setup-uv@ed21f2f24f8dd64503750218de024bcf64c7250a # v7
+      uses: astral-sh/setup-uv@681c641aba71e4a1c380be3ab5e12ad51f415867 # v7
       with:
         version: ${{ env.UV_VERSION }}
         python-version: ${{ env.PYTHON_VERSION }}
@@ -82,7 +82,7 @@ jobs:
         python-version: ${{ matrix.python-version }}
 
     - name: Install uv
-      uses: astral-sh/setup-uv@ed21f2f24f8dd64503750218de024bcf64c7250a # v7
+      uses: astral-sh/setup-uv@681c641aba71e4a1c380be3ab5e12ad51f415867 # v7
       with:
         version: ${{ env.UV_VERSION }}
         python-version: ${{ matrix.python-version }}
@@ -134,7 +134,7 @@ jobs:
         python-version: ${{ env.PYTHON_VERSION }}
 
     - name: Install uv
-      uses: astral-sh/setup-uv@ed21f2f24f8dd64503750218de024bcf64c7250a   # v7
+      uses: astral-sh/setup-uv@681c641aba71e4a1c380be3ab5e12ad51f415867   # v7
       with:
         version: ${{ env.UV_VERSION }}
         python-version: ${{ env.PYTHON_VERSION }}
@@ -198,7 +198,7 @@ jobs:
         python-version: ${{ env.PYTHON_VERSION }}
 
     - name: Install uv
-      uses: astral-sh/setup-uv@ed21f2f24f8dd64503750218de024bcf64c7250a # v7
+      uses: astral-sh/setup-uv@681c641aba71e4a1c380be3ab5e12ad51f415867 # v7
       with:
         version: ${{ env.UV_VERSION }}
         python-version: ${{ env.PYTHON_VERSION }}

{lifx_async-4.7.4 → lifx_async-4.8.0}/.github/workflows/docs.yml

@@ -35,7 +35,7 @@ jobs:
         python-version: ${{ env.PYTHON_VERSION }}
 
     - name: Install uv
-      uses: astral-sh/setup-uv@ed21f2f24f8dd64503750218de024bcf64c7250a # v7
+      uses: astral-sh/setup-uv@681c641aba71e4a1c380be3ab5e12ad51f415867 # v7
       with:
         version: ${{ env.UV_VERSION }}
         python-version: ${{ env.PYTHON_VERSION }}
@@ -69,7 +69,7 @@ jobs:
         python-version: ${{ env.PYTHON_VERSION }}
 
     - name: Install uv
-      uses: astral-sh/setup-uv@ed21f2f24f8dd64503750218de024bcf64c7250a # v7
+      uses: astral-sh/setup-uv@681c641aba71e4a1c380be3ab5e12ad51f415867 # v7
       with:
         version: ${{ env.UV_VERSION }}
         python-version: ${{ env.PYTHON_VERSION }}
@@ -97,7 +97,7 @@ jobs:
         python-version: ${{ env.PYTHON_VERSION }}
 
     - name: Install uv
-      uses: astral-sh/setup-uv@ed21f2f24f8dd64503750218de024bcf64c7250a # v7
+      uses: astral-sh/setup-uv@681c641aba71e4a1c380be3ab5e12ad51f415867 # v7
       with:
         version: ${{ env.UV_VERSION }}
         python-version: ${{ env.PYTHON_VERSION }}

{lifx_async-4.7.4 → lifx_async-4.8.0}/CLAUDE.md

@@ -122,6 +122,11 @@ uv run mkdocs gh-deploy
    - `discovery.py`: Device discovery via broadcast with `DiscoveredDevice` dataclass
    - `connection.py`: Device connection with retry logic and lazy opening
    - `message.py`: Message building and parsing with `MessageBuilder`
+   - `mdns/`: mDNS/DNS-SD discovery module (zero-dependency, stdlib only)
+     - `discovery.py`: `discover_lifx_services()` and `discover_devices_mdns()`
+     - `dns.py`: DNS wire format parser for PTR, SRV, A, TXT records
+     - `transport.py`: `MdnsTransport` class for multicast UDP
+     - `types.py`: `LifxServiceRecord` dataclass
    - Lazy connection opening (auto-opens on first request)
 
 3. **Device Layer** (`src/lifx/devices/`)
@@ -136,7 +141,8 @@ uv run mkdocs gh-deploy
 
 4. **High-Level API** (`src/lifx/api.py`)
 
-   - `discover()`: Async generator yielding devices as they're discovered
+   - `discover()`: Async generator yielding devices via UDP broadcast
+   - `discover_mdns()`: Async generator yielding devices via mDNS (faster, single query)
    - `find_by_serial()`: Find specific device by serial number
    - `find_by_label()`: Async generator yielding devices matching label (exact or substring)
    - `find_by_ip()`: Find device by IP address using targeted broadcast
@@ -616,9 +622,9 @@ The `discover_devices()` function implements DoS protection through:
 
 ## Testing Strategy
 
-- **768 tests total** (comprehensive coverage across all layers)
+- **1075+ tests total** (comprehensive coverage across all layers)
 - **Protocol Layer**: 136 tests (serialization, header, packets, generator validation)
-- **Network Layer**: 86 tests (transport, discovery, connection, message, async generator requests)
+- **Network Layer**: 149 tests (transport, discovery, connection, message, mDNS, async generator requests)
 - **Device Layer**: 157 tests (base, light, hev, infrared, multizone, tile)
 - **API Layer**: 60 tests (discovery, batch operations, organization, themes, error handling)
 - **Utilities**: 329 tests (color conversion, product registry, RGB roundtrip, effects, themes)
@@ -675,7 +681,11 @@ tests/
 │   ├── test_discovery_errors.py     # Discovery error handling tests
 │   ├── test_connection.py       # Connection management tests
 │   ├── test_message.py          # Message building/parsing tests
-│   └── test_concurrent_requests.py  # Concurrent request tests
+│   ├── test_concurrent_requests.py  # Concurrent request tests
+│   └── test_mdns/               # mDNS discovery tests
+│       ├── test_dns.py          # DNS parser tests
+│       ├── test_transport.py    # mDNS transport tests
+│       └── test_discovery.py    # mDNS discovery tests
 ├── test_devices/
 │   ├── test_base.py             # Base device tests
 │   ├── test_light.py            # Light device tests
@@ -792,6 +802,11 @@ Critical constants are defined in `src/lifx/const.py`:
 - `MAX_RESPONSE_TIME`: Maximum response time for local network devices (0.5s)
 - `IDLE_TIMEOUT_MULTIPLIER`: Idle timeout after last response (4.0)
 
+**mDNS Constants:**
+- `MDNS_ADDRESS`: Multicast address for mDNS (224.0.0.251)
+- `MDNS_PORT`: mDNS port (5353)
+- `LIFX_MDNS_SERVICE`: LIFX service type (_lifx._udp.local)
+
 **UUID Namespaces:**
 - `LIFX_LOCATION_NAMESPACE`: UUID namespace for generating location UUIDs
 - `LIFX_GROUP_NAMESPACE`: UUID namespace for generating group UUIDs

{lifx_async-4.7.4 → lifx_async-4.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lifx-async
-Version: 4.7.4
+Version: 4.8.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.7.4 → lifx_async-4.8.0}/docs/api/index.md

@@ -20,9 +20,14 @@ lifx/
 │   └── matrix.py            # MatrixLight (2D matrix devices: tiles, candle, path)
 ├── network/                  # Network layer
 │   ├── connection.py        # Device connections with lazy opening
-│   ├── discovery.py         # Network device discovery
+│   ├── discovery.py         # Network device discovery (UDP broadcast)
 │   ├── message.py           # Message building and parsing
-│   └── transport.py         # UDP transport
+│   ├── transport.py         # UDP transport
+│   └── mdns/                # mDNS/DNS-SD discovery
+│       ├── discovery.py     # mDNS discovery functions
+│       ├── dns.py           # DNS wire format parser
+│       ├── transport.py     # Multicast UDP transport
+│       └── types.py         # LifxServiceRecord dataclass
 ├── products/                 # Product registry
 │   ├── registry.py          # Auto-generated product database
 │   ├── generator.py         # Generator to download/parse products.json
@@ -43,7 +48,8 @@ lifx/
 
 Main entry points for most users:
 
-- [`discover()`](high-level.md#lifx.api.discover) - Simple device discovery
+- [`discover()`](high-level.md#lifx.api.discover) - Device discovery via UDP broadcast
+- [`discover_mdns()`](high-level.md#lifx.api.discover_mdns) - Device discovery via mDNS (faster)
 - [`find_by_serial()`](high-level.md#lifx.api.find_by_serial) - Find device by serial number
 - [`find_by_label()`](high-level.md#lifx.api.find_by_label) - Find devices by label (exact or substring)
 - [`find_by_ip()`](high-level.md#lifx.api.find_by_ip) - Find device by IP address
@@ -71,7 +77,9 @@ Work with colors:
 
 Low-level network operations:
 
-- [`discover_devices()`](network.md#lifx.network.discovery.discover_devices) - Low-level discovery
+- [`discover_devices()`](network.md#lifx.network.discovery.discover_devices) - Low-level UDP discovery
+- [`discover_lifx_services()`](network.md#lifx.network.mdns.discover_lifx_services) - Low-level mDNS discovery
+- [`LifxServiceRecord`](network.md#lifx.network.mdns.LifxServiceRecord) - mDNS service record
 - [`DeviceConnection`](network.md#lifx.network.connection.DeviceConnection) - Device connections
 
 ### Products Registry

{lifx_async-4.7.4 → lifx_async-4.8.0}/docs/changelog.md

@@ -2,6 +2,22 @@
 
 <!-- version list -->
 
+## v4.8.0 (2025-12-20)
+
+### Features
+
+- **network**: Add mDNS/DNS-SD discovery for LIFX devices
+  ([`f25987d`](https://github.com/Djelibeybi/lifx-async/commit/f25987d9357d395209dd7d346787671d85bf1371))
+
+
+## v4.7.5 (2025-12-16)
+
+### Bug Fixes
+
+- **devices**: Override set_color in CeilingLight to track component state
+  ([`0d20563`](https://github.com/Djelibeybi/lifx-async/commit/0d20563c170363229ab17620398283bd85ee7829))
+
+
 ## v4.7.4 (2025-12-16)
 
 ### Performance Improvements

{lifx_async-4.7.4 → lifx_async-4.8.0}/docs/getting-started/quickstart.md

@@ -24,6 +24,27 @@ async def main():
 asyncio.run(main())
 ```
 
+**Alternative: mDNS Discovery**
+
+For faster discovery with device type detection in a single query:
+
+```python
+import asyncio
+from lifx import discover_mdns
+
+
+async def main():
+    async for device in discover_mdns():
+        async with device:
+            color, power, label = await device.get_color()
+            print(f"{label}: {type(device).__name__}")
+
+
+asyncio.run(main())
+```
+
+mDNS discovery is faster because it gets device type information directly from the mDNS response, eliminating extra network queries.
+
 ### 2. Control a Light
 
 Turn on the first discovered light, then change its color:

{lifx_async-4.7.4 → lifx_async-4.8.0}/docs/user-guide/advanced-usage.md

@@ -4,6 +4,7 @@ This guide covers advanced lifx patterns and techniques for building robust LIFX
 
 ## Table of Contents
 
+- [Discovery Methods](#discovery-methods)
 - [Storing State](#storing-state)
 - [Connection Management](#connection-management)
 - [Concurrency Patterns](#concurrency-patterns)
@@ -12,6 +13,76 @@ This guide covers advanced lifx patterns and techniques for building robust LIFX
 - [Custom Effects](#custom-effects)
 - [Performance Optimization](#performance-optimization)
 
+## Discovery Methods
+
+lifx-async provides two discovery methods with different trade-offs:
+
+### UDP Broadcast Discovery
+
+The traditional discovery method broadcasts to all devices on the network:
+
+```python
+from lifx import discover
+
+async def broadcast_discovery():
+    async for device in discover(timeout=5.0):
+        async with device:
+            color, power, label = await device.get_color()
+            print(f"Found: {label} ({type(device).__name__})")
+```
+
+**Characteristics:**
+
+- Sends 1 broadcast + N queries (one per device for type detection)
+- Works on any local network
+- May miss devices on other subnets
+
+### mDNS Discovery
+
+mDNS discovery uses DNS-SD to find devices with a single multicast query:
+
+```python
+from lifx import discover_mdns
+
+async def mdns_discovery():
+    async for device in discover_mdns(timeout=5.0):
+        async with device:
+            color, power, label = await device.get_color()
+            print(f"Found: {label} ({type(device).__name__})")
+```
+
+**Characteristics:**
+
+- Single network query (device type in TXT record)
+- Faster discovery with immediate type detection
+- Can work across subnets with an mDNS reflector
+- Zero dependencies (uses Python stdlib only)
+
+### Low-Level mDNS API
+
+For raw mDNS data without device instantiation:
+
+```python
+from lifx import discover_lifx_services
+
+async def raw_mdns_discovery():
+    async for record in discover_lifx_services(timeout=5.0):
+        print(f"Serial: {record.serial}")
+        print(f"IP: {record.ip}:{record.port}")
+        print(f"Product ID: {record.product_id}")
+        print(f"Firmware: {record.firmware}")
+```
+
+### Choosing a Discovery Method
+
+| Scenario | Recommended Method |
+|----------|-------------------|
+| General use | `discover()` or `discover_mdns()` |
+| Fastest discovery | `discover_mdns()` |
+| Cross-subnet (with reflector) | `discover_mdns()` |
+| Maximum compatibility | `discover()` |
+| Raw device data | `discover_lifx_services()` |
+
 ## Storing State
 
 Device properties return cached values that were last retrieved from the device.

lifx_async-4.8.0/examples/14_mdns_discovery.py

@@ -0,0 +1,76 @@
+#!/usr/bin/env python3
+"""Example: Discover LIFX devices using mDNS.
+
+This example demonstrates how to discover LIFX devices on your local network
+using mDNS/DNS-SD instead of UDP broadcast. mDNS discovery has several advantages:
+
+- Single network query (vs 1+N for broadcast discovery)
+- Device type detection without extra queries (from TXT record)
+- Can work across subnets with an mDNS reflector
+
+Usage:
+    uv run python examples/14_mdns_discovery.py
+"""
+
+from __future__ import annotations
+
+import asyncio
+
+import lifx
+
+
+async def discover_with_mdns() -> None:
+    """Discover devices using mDNS and print their info."""
+    print("Discovering LIFX devices via mDNS...")
+    print("-" * 60)
+
+    device_count = 0
+    async for device in lifx.discover_mdns(timeout=5.0):
+        device_count += 1
+        async with device:
+            # get_color() returns color, power, and label in a single request
+            color, power, label = await device.get_color()
+            power_str = "ON" if power > 0 else "OFF"
+
+            print(f"\nDevice #{device_count}")
+            print(f"  Type:   {type(device).__name__}")
+            print(f"  Label:  {label}")
+            print(f"  Serial: {device.serial}")
+            print(f"  IP:     {device.ip}:{device.port}")
+            print(f"  Power:  {power_str}")
+            print(
+                f"  Color:  H={color.hue:.0f} S={color.saturation:.0%} "
+                f"B={color.brightness:.0%} K={color.kelvin}"
+            )
+
+    print("-" * 60)
+    if device_count == 0:
+        print("No devices found. Make sure LIFX devices are on your network.")
+    else:
+        print(f"Found {device_count} device(s)")
+
+
+async def discover_raw_records() -> None:
+    """Discover devices using low-level mDNS API (raw service records)."""
+    print("\nLow-level mDNS discovery (raw service records):")
+    print("-" * 60)
+
+    async for record in lifx.discover_lifx_services(timeout=3.0):
+        print(f"  Serial: {record.serial}")
+        print(f"  IP: {record.ip}:{record.port}")
+        print(f"  Product ID: {record.product_id}")
+        print(f"  Firmware: {record.firmware}")
+        print()
+
+
+async def main() -> None:
+    """Run both discovery methods."""
+    # High-level API - yields device instances (Light, MatrixLight, etc.)
+    await discover_with_mdns()
+
+    # Low-level API - yields raw mDNS service records
+    await discover_raw_records()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

{lifx_async-4.7.4 → lifx_async-4.8.0}/pyproject.toml

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