lifx-async 5.1.0__tar.gz → 5.1.1__tar.gz

{lifx_async-5.1.0 → lifx_async-5.1.1}/.github/workflows/ci.yml

@@ -32,7 +32,7 @@ jobs:
     name: Code Quality
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6
+    - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
 
     - name: Set up Python
       uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
@@ -40,7 +40,7 @@ jobs:
         python-version: ${{ env.PYTHON_VERSION }}
 
     - name: Install uv
-      uses: astral-sh/setup-uv@61cb8a9741eeb8a550a1b8544337180c0fc8476b # v7
+      uses: astral-sh/setup-uv@803947b9bd8e9f986429fa0c5a41c367cd732b41 # v7
       with:
         version: ${{ env.UV_VERSION }}
         python-version: ${{ env.PYTHON_VERSION }}
@@ -68,7 +68,7 @@ jobs:
     needs: quality
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6
+    - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
 
     - name: Set up Python
       uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
@@ -76,7 +76,7 @@ jobs:
         python-version: ${{ env.PYTHON_VERSION }}
 
     - name: Install uv
-      uses: astral-sh/setup-uv@61cb8a9741eeb8a550a1b8544337180c0fc8476b # v7
+      uses: astral-sh/setup-uv@803947b9bd8e9f986429fa0c5a41c367cd732b41 # v7
       with:
         version: ${{ env.UV_VERSION }}
         python-version: ${{ env.PYTHON_VERSION }}
@@ -115,7 +115,7 @@ jobs:
         os: [ubuntu-latest, macos-latest, windows-latest]
         python-version: ['3.10', '3.11', '3.12', '3.13', '3.14']
     steps:
-    - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6
+    - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
 
     - name: Set up Python ${{ matrix.python-version }}
       uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
@@ -123,7 +123,7 @@ jobs:
         python-version: ${{ matrix.python-version }}
 
     - name: Install uv
-      uses: astral-sh/setup-uv@61cb8a9741eeb8a550a1b8544337180c0fc8476b # v7
+      uses: astral-sh/setup-uv@803947b9bd8e9f986429fa0c5a41c367cd732b41 # v7
       with:
         version: ${{ env.UV_VERSION }}
         python-version: ${{ matrix.python-version }}
@@ -167,7 +167,7 @@ jobs:
     if: github.event_name == 'push' && github.ref_name == 'main'
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8   # v6
+    - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd   # v6
 
     - name: Set up Python
       uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405   # v6
@@ -175,7 +175,7 @@ jobs:
         python-version: ${{ env.PYTHON_VERSION }}
 
     - name: Install uv
-      uses: astral-sh/setup-uv@61cb8a9741eeb8a550a1b8544337180c0fc8476b   # v7
+      uses: astral-sh/setup-uv@803947b9bd8e9f986429fa0c5a41c367cd732b41   # v7
       with:
         version: ${{ env.UV_VERSION }}
         python-version: ${{ env.PYTHON_VERSION }}
@@ -228,7 +228,7 @@ jobs:
 
     steps:
     - name: Checkout repository on release branch
-      uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6
+      uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
       with:
         ref: ${{ github.head_ref || github.ref_name }}
         fetch-depth: 0
@@ -240,7 +240,7 @@ jobs:
         python-version: ${{ env.PYTHON_VERSION }}
 
     - name: Install uv
-      uses: astral-sh/setup-uv@61cb8a9741eeb8a550a1b8544337180c0fc8476b # v7
+      uses: astral-sh/setup-uv@803947b9bd8e9f986429fa0c5a41c367cd732b41 # v7
       with:
         version: ${{ env.UV_VERSION }}
         python-version: ${{ env.PYTHON_VERSION }}

{lifx_async-5.1.0 → lifx_async-5.1.1}/.github/workflows/docs.yml

@@ -25,7 +25,7 @@ jobs:
   build-docs:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6
+    - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
       with:
         fetch-depth: 0    # Fetch all history for git-revision-date-localized
 
@@ -35,7 +35,7 @@ jobs:
         python-version: ${{ env.PYTHON_VERSION }}
 
     - name: Install uv
-      uses: astral-sh/setup-uv@61cb8a9741eeb8a550a1b8544337180c0fc8476b # v7
+      uses: astral-sh/setup-uv@803947b9bd8e9f986429fa0c5a41c367cd732b41 # v7
       with:
         version: ${{ env.UV_VERSION }}
         python-version: ${{ env.PYTHON_VERSION }}
@@ -59,7 +59,7 @@ jobs:
     if: github.ref == 'refs/heads/main' && github.event_name == 'push'
     needs: build-docs
     steps:
-    - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6
+    - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
       with:
         fetch-depth: 0
 
@@ -69,7 +69,7 @@ jobs:
         python-version: ${{ env.PYTHON_VERSION }}
 
     - name: Install uv
-      uses: astral-sh/setup-uv@61cb8a9741eeb8a550a1b8544337180c0fc8476b # v7
+      uses: astral-sh/setup-uv@803947b9bd8e9f986429fa0c5a41c367cd732b41 # v7
       with:
         version: ${{ env.UV_VERSION }}
         python-version: ${{ env.PYTHON_VERSION }}
@@ -89,7 +89,7 @@ jobs:
   validate-links:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6
+    - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
 
     - name: Set up Python
       uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
@@ -97,7 +97,7 @@ jobs:
         python-version: ${{ env.PYTHON_VERSION }}
 
     - name: Install uv
-      uses: astral-sh/setup-uv@61cb8a9741eeb8a550a1b8544337180c0fc8476b # v7
+      uses: astral-sh/setup-uv@803947b9bd8e9f986429fa0c5a41c367cd732b41 # v7
       with:
         version: ${{ env.UV_VERSION }}
         python-version: ${{ env.PYTHON_VERSION }}

{lifx_async-5.1.0 → lifx_async-5.1.1}/PKG-INFO

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

@@ -2,6 +2,17 @@
 
 <!-- version list -->
 
+## v5.1.1 (2026-02-06)
+
+### Performance Improvements
+
+- Optimize device initialization and packet sending
+  ([`865c4e3`](https://github.com/Djelibeybi/lifx-async/commit/865c4e32f696881a4e0ed2932eb014c4136d0554))
+
+- Pure-Python optimizations for protocol, network, and animation layers
+  ([`a9a4bd4`](https://github.com/Djelibeybi/lifx-async/commit/a9a4bd40e35095c079339b336d82f1f5d509560a))
+
+
 ## v5.1.0 (2026-01-24)
 
 ### Bug Fixes

{lifx_async-5.1.0 → lifx_async-5.1.1}/examples/15_animation.py

@@ -6,14 +6,30 @@ Path) or multizone (Strip, Beam) device and runs an appropriate animation.
 
 The animation module sends frames via direct UDP for maximum throughput -
 no connection layer overhead, no ACKs, just fire packets as fast as possible.
+
+Use --profile to run performance benchmarks:
+  --profile alone: runs synthetic micro-benchmarks (no device needed)
+  --profile with --serial/--ip: also profiles the animation loop against a device
 """
 
 import argparse
 import asyncio
 import math
+import statistics
 import time
 
-from lifx import Animator, MatrixLight, MultiZoneLight, find_by_ip, find_by_serial
+from lifx import (
+    Animator,
+    Device,
+    MatrixLight,
+    MultiZoneLight,
+    find_by_ip,
+    find_by_serial,
+)
+from lifx.animation.packets import MatrixPacketGenerator, MultiZonePacketGenerator
+from lifx.protocol.header import LifxHeader
+from lifx.protocol.packets import Light
+from lifx.protocol.protocol_types import LightHsbk
 
 
 def print_animator_info(animator: Animator) -> None:
@@ -25,6 +41,207 @@ def print_animator_info(animator: Animator) -> None:
     print("---------------------\n")
 
 
+def percentile_stats(times_ms: list[float]) -> dict[str, float]:
+    """Compute summary statistics from a list of times in milliseconds."""
+    if not times_ms:
+        return {
+            "mean": 0.0,
+            "median": 0.0,
+            "p95": 0.0,
+            "p99": 0.0,
+            "min": 0.0,
+            "max": 0.0,
+        }
+    times_ms.sort()
+    n = len(times_ms)
+    return {
+        "mean": statistics.mean(times_ms),
+        "median": statistics.median(times_ms),
+        "p95": times_ms[int(n * 0.95)],
+        "p99": times_ms[int(n * 0.99)],
+        "min": times_ms[0],
+        "max": times_ms[-1],
+    }
+
+
+def print_stats(label: str, stats: dict[str, float]) -> None:
+    """Print a single stats line."""
+    print(
+        f"  {label}:\n"
+        f"    mean={stats['mean']:.3f}ms  median={stats['median']:.3f}ms  "
+        f"p95={stats['p95']:.3f}ms  p99={stats['p99']:.3f}ms  "
+        f"min={stats['min']:.3f}ms  max={stats['max']:.3f}ms"
+    )
+
+
+async def run_profile(
+    device: MatrixLight | MultiZoneLight,
+    iterations: int = 2000,
+    warmup: int = 200,
+) -> None:
+    """Profile the animation loop against a real device."""
+    is_matrix = isinstance(device, MatrixLight)
+
+    if is_matrix:
+        animator = await Animator.for_matrix(device)
+        canvas_width = animator.canvas_width
+        canvas_height = animator.canvas_height
+    else:
+        animator = await Animator.for_multizone(device)
+        canvas_width = animator.pixel_count
+        canvas_height = 1
+
+    pixel_count = animator.pixel_count
+
+    # Pre-compute wave constants for matrix
+    wave_angle = math.radians(30)
+    cos_wave = math.cos(wave_angle)
+    sin_wave = math.sin(wave_angle)
+    max_pos = canvas_width * cos_wave + canvas_height * sin_wave
+
+    gen_times: list[float] = []
+    send_times: list[float] = []
+
+    total_iterations = warmup + iterations
+    print(
+        f"\n=== Animation Profile ({iterations} iterations, "
+        f"{'matrix' if is_matrix else 'multizone'} "
+        f"{canvas_width}x{canvas_height}, {pixel_count} pixels) ==="
+    )
+    print(f"  Warmup: {warmup} iterations")
+
+    try:
+        for i in range(total_iterations):
+            hue_offset = (i * 1000) % 65536
+
+            # Time frame generation
+            t0 = time.perf_counter()
+            if is_matrix:
+                frame = []
+                for y in range(canvas_height):
+                    for x in range(canvas_width):
+                        pos = x * cos_wave + y * sin_wave
+                        hue = int((pos / max_pos) * 65535 + hue_offset) % 65536
+                        frame.append((hue, 65535, 65535, 3500))
+            else:
+                frame = []
+                for j in range(pixel_count):
+                    hue_val = int((j / pixel_count) * 65536)
+                    hue = (hue_offset + hue_val) % 65536
+                    frame.append((hue, 65535, 65535, 3500))
+            t1 = time.perf_counter()
+
+            # Time send_frame
+            animator.send_frame(frame)
+            t2 = time.perf_counter()
+
+            if i >= warmup:
+                gen_times.append((t1 - t0) * 1000)
+                send_times.append((t2 - t1) * 1000)
+    finally:
+        animator.close()
+
+    total_times = [g + s for g, s in zip(gen_times, send_times)]
+
+    print()
+    print_stats("Frame generation", percentile_stats(gen_times))
+    print_stats("send_frame (orient + pack + send)", percentile_stats(send_times))
+    print_stats("Total per-frame", percentile_stats(total_times))
+
+    if total_times:
+        mean_total = statistics.mean(total_times)
+        if mean_total > 0:
+            throughput = 1000.0 / mean_total
+            print(f"\n  Throughput: {throughput:,.0f} frames/sec")
+
+
+def _bench(label: str, func: object, n: int) -> None:
+    """Run a tight-loop benchmark and print results."""
+    t0 = time.perf_counter()
+    for _ in range(n):
+        func()  # type: ignore[operator]
+    elapsed = time.perf_counter() - t0
+    rate = n / elapsed
+    per_call = elapsed / n * 1000
+    print(
+        f"{label}:\n"
+        f"  {n:,} calls in {elapsed:.2f}s  "
+        f"({rate:,.0f} calls/sec, {per_call:.4f}ms/call)"
+    )
+
+
+def run_synthetic_benchmarks() -> None:
+    """Run synthetic micro-benchmarks of optimized code paths."""
+    print("\n=== Synthetic Benchmarks ===\n")
+
+    dummy_target = b"\xd0\x73\xd5\x01\x02\x03"
+    dummy_source = 12345
+
+    # --- update_colors: matrix (5 tiles, 320 pixels) ---
+    matrix_gen = MatrixPacketGenerator(tile_count=5, tile_width=8, tile_height=8)
+    matrix_templates = matrix_gen.create_templates(dummy_source, dummy_target)
+    matrix_pixels = matrix_gen.pixel_count()
+    matrix_hsbk = [(32768, 65535, 32768, 3500)] * matrix_pixels
+
+    n = 100_000
+    _bench(
+        f"update_colors (matrix, 5 tiles, {matrix_pixels}px)",
+        lambda: matrix_gen.update_colors(matrix_templates, matrix_hsbk),
+        n,
+    )
+
+    # --- update_colors: multizone (82 zones) ---
+    mz_gen = MultiZonePacketGenerator(zone_count=82)
+    mz_templates = mz_gen.create_templates(dummy_source, dummy_target)
+    mz_hsbk = [(32768, 65535, 32768, 3500)] * 82
+
+    print()
+    _bench(
+        "update_colors (multizone, 82 zones)",
+        lambda: mz_gen.update_colors(mz_templates, mz_hsbk),
+        n,
+    )
+
+    # --- LifxHeader.pack() ---
+    header = LifxHeader.create(
+        pkt_type=102,
+        source=dummy_source,
+        target=dummy_target,
+        payload_size=13,
+    )
+    n_header = 500_000
+
+    print()
+    _bench("LifxHeader.pack()", header.pack, n_header)
+
+    # --- LifxHeader.unpack() ---
+    packed_header = header.pack()
+
+    print()
+    _bench(
+        "LifxHeader.unpack()",
+        lambda: LifxHeader.unpack(packed_header),
+        n_header,
+    )
+
+    # --- Packet.pack (Light.SetColor) ---
+    hsbk = LightHsbk(hue=32768, saturation=65535, brightness=32768, kelvin=3500)
+    packet = Light.SetColor(color=hsbk, duration=1000)
+
+    print()
+    _bench("Packet.pack (Light.SetColor)", packet.pack, n)
+
+    # --- Packet.unpack (Light.SetColor) ---
+    packed_packet = packet.pack()
+
+    print()
+    _bench(
+        "Packet.unpack (Light.SetColor)",
+        lambda: Light.SetColor.unpack(packed_packet),
+        n,
+    )
+
+
 async def run_matrix_animation(
     device: MatrixLight,
     duration: float = 10.0,
@@ -216,27 +433,44 @@ async def run_multizone_animation(
 
 
 async def main(
-    serial: str,
+    serial: str | None = None,
     ip: str | None = None,
     duration: float = 10.0,
     fps: float = 30.0,
+    profile: bool = False,
+    iterations: int = 2000,
+    warmup: int = 200,
 ) -> None:
     """Find device and run appropriate animation."""
+    if profile and not serial and not ip:
+        # Synthetic-only mode
+        print("=" * 70)
+        print("LIFX Animation Profiler (synthetic benchmarks only)")
+        print("=" * 70)
+        run_synthetic_benchmarks()
+        return
+
+    if not serial and not ip:
+        print("Error: --serial or --ip is required (unless using --profile alone)")
+        return
+
     print("=" * 70)
-    print("LIFX Animation Example")
+    print("LIFX Animation Example" + (" (profiling)" if profile else ""))
     print("=" * 70)
 
     # Find the device
-    if ip:
+    if serial and ip:
+        # Both serial and IP provided - connect directly without discovery
+        print(f"\nConnecting directly to {ip} (serial: {serial})")
+        device = await Device.connect(ip=ip, serial=serial)
+    elif ip:
         print(f"\nSearching for device at IP: {ip}")
         device = await find_by_ip(ip)
         if device is None:
             print(f"No device found at IP '{ip}'")
             return
-        # Verify serial matches if both provided
-        if device.serial.lower().replace(":", "") != serial.lower().replace(":", ""):
-            print(f"Warning: Device serial {device.serial} doesn't match {serial}")
     else:
+        assert serial is not None
         print(f"\nSearching for device with serial: {serial}")
         device = await find_by_serial(serial)
         if device is None:
@@ -294,20 +528,32 @@ async def main(
             await device.set_power(True)
             await asyncio.sleep(1)
 
-        # Run appropriate animation
+        # Run appropriate animation or profile
         try:
-            if is_matrix:
-                assert isinstance(device, MatrixLight)
-                await run_matrix_animation(device, duration, fps)
+            if profile:
+                if is_matrix:
+                    assert isinstance(device, MatrixLight)
+                    await run_profile(device, iterations, warmup)
+                else:
+                    assert isinstance(device, MultiZoneLight)
+                    await run_profile(device, iterations, warmup)
             else:
-                assert isinstance(device, MultiZoneLight)
-                await run_multizone_animation(device, duration, fps)
+                if is_matrix:
+                    assert isinstance(device, MatrixLight)
+                    await run_matrix_animation(device, duration, fps)
+                else:
+                    assert isinstance(device, MultiZoneLight)
+                    await run_multizone_animation(device, duration, fps)
         finally:
             # Restore power state
             if was_off:
                 print("\nTurning device back OFF...")
                 await device.set_power(False)
 
+    # Always run synthetic benchmarks after device profiling
+    if profile:
+        run_synthetic_benchmarks()
+
     print("\n" + "=" * 70)
 
 
@@ -326,6 +572,12 @@ Examples:
   # Run animation for 30 seconds at 60 FPS
   python 15_animation.py --serial d073d5123456 --duration 30 --fps 60
 
+  # Run synthetic benchmarks only (no device needed)
+  python 15_animation.py --profile
+
+  # Profile animation loop against a device + synthetic benchmarks
+  python 15_animation.py --serial d073d5123456 --ip 192.168.1.100 --profile
+
   # Serial number formats (both work):
   python 15_animation.py --serial d073d5123456
   python 15_animation.py --serial d0:73:d5:12:34:56
@@ -334,7 +586,6 @@ Examples:
     parser.add_argument(
         "--serial",
         "-s",
-        required=True,
         help="Device serial number (12 hex digits, with or without colons)",
     )
     parser.add_argument(
@@ -356,9 +607,29 @@ Examples:
         default=30.0,
         help="Target frames per second (default: 30)",
     )
+    parser.add_argument(
+        "--profile",
+        action="store_true",
+        help="Enable profiling mode (no sleep between frames)",
+    )
+    parser.add_argument(
+        "--iterations",
+        type=int,
+        default=2000,
+        help="Number of profiling iterations (default: 2000)",
+    )
+    parser.add_argument(
+        "--warmup",
+        type=int,
+        default=200,
+        help="Warmup iterations excluded from stats (default: 200)",
+    )
 
     args = parser.parse_args()
 
+    if not args.profile and not args.serial:
+        parser.error("--serial is required unless using --profile alone")
+
     try:
         asyncio.run(
             main(
@@ -366,6 +637,9 @@ Examples:
                 args.ip,
                 args.duration,
                 args.fps,
+                args.profile,
+                args.iterations,
+                args.warmup,
             )
         )
     except KeyboardInterrupt: