lifx-async 4.5.0__tar.gz → 4.5.1__tar.gz

{lifx_async-4.5.0 → lifx_async-4.5.1}/.github/workflows/ci.yml

@@ -40,7 +40,7 @@ jobs:
         python-version: ${{ env.PYTHON_VERSION }}
 
     - name: Install uv
-      uses: astral-sh/setup-uv@1e862dfacbd1d6d858c55d9b792c756523627244 # v7
+      uses: astral-sh/setup-uv@ed21f2f24f8dd64503750218de024bcf64c7250a # 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@1e862dfacbd1d6d858c55d9b792c756523627244 # v7
+      uses: astral-sh/setup-uv@ed21f2f24f8dd64503750218de024bcf64c7250a # 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@1e862dfacbd1d6d858c55d9b792c756523627244   # v7
+      uses: astral-sh/setup-uv@ed21f2f24f8dd64503750218de024bcf64c7250a   # 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@1e862dfacbd1d6d858c55d9b792c756523627244 # v7
+      uses: astral-sh/setup-uv@ed21f2f24f8dd64503750218de024bcf64c7250a # v7
       with:
         version: ${{ env.UV_VERSION }}
         python-version: ${{ env.PYTHON_VERSION }}

{lifx_async-4.5.0 → lifx_async-4.5.1}/.github/workflows/docs.yml

@@ -35,7 +35,7 @@ jobs:
         python-version: ${{ env.PYTHON_VERSION }}
 
     - name: Install uv
-      uses: astral-sh/setup-uv@1e862dfacbd1d6d858c55d9b792c756523627244 # v7
+      uses: astral-sh/setup-uv@ed21f2f24f8dd64503750218de024bcf64c7250a # 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@1e862dfacbd1d6d858c55d9b792c756523627244 # v7
+      uses: astral-sh/setup-uv@ed21f2f24f8dd64503750218de024bcf64c7250a # 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@1e862dfacbd1d6d858c55d9b792c756523627244 # v7
+      uses: astral-sh/setup-uv@ed21f2f24f8dd64503750218de024bcf64c7250a # v7
       with:
         version: ${{ env.UV_VERSION }}
         python-version: ${{ env.PYTHON_VERSION }}

{lifx_async-4.5.0 → lifx_async-4.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lifx-async
-Version: 4.5.0
+Version: 4.5.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-4.5.0 → lifx_async-4.5.1}/docs/api/devices.md

@@ -81,6 +81,19 @@ The `MatrixLight` class controls LIFX matrix devices (tiles, candle, path) with
       filters:
         - "!^_"
 
+## Ceiling Light
+
+The `CeilingLight` class extends `MatrixLight` with independent control over uplight and downlight components for LIFX Ceiling fixtures.
+
+::: lifx.devices.ceiling.CeilingLight
+    options:
+      show_root_heading: true
+      heading_level: 3
+      members_order: source
+      show_if_no_docstring: false
+      filters:
+        - "!^_"
+
 ## Device Properties
 
 ### MAC Address
@@ -268,3 +281,34 @@ async def main():
         # Stop the effect
         await light.set_effect(effect_type=FirmwareEffect.OFF)
 ```
+
+### Ceiling Light Control
+
+```python
+from lifx import CeilingLight, HSBK
+
+
+async def main():
+    async with await CeilingLight.from_ip("192.168.1.100") as ceiling:
+        # Set downlight to warm white
+        await ceiling.set_downlight_colors(
+            HSBK(hue=0, saturation=0, brightness=0.8, kelvin=3000)
+        )
+
+        # Set uplight to a dim ambient glow
+        await ceiling.set_uplight_color(
+            HSBK(hue=30, saturation=0.2, brightness=0.3, kelvin=2700)
+        )
+
+        # Turn uplight off (stores color for later restoration)
+        await ceiling.turn_uplight_off()
+
+        # Turn uplight back on (restores previous color)
+        await ceiling.turn_uplight_on()
+
+        # Check component state
+        if ceiling.downlight_is_on:
+            print("Downlight is currently on")
+```
+
+For detailed CeilingLight usage, see the [Ceiling Lights User Guide](../user-guide/ceiling-lights.md).

{lifx_async-4.5.0 → lifx_async-4.5.1}/docs/changelog.md

@@ -2,6 +2,14 @@
 
 <!-- version list -->
 
+## v4.5.1 (2025-12-11)
+
+### Bug Fixes
+
+- **devices**: Export CeilingLight add add user guide and API documentation
+  ([`10e0089`](https://github.com/Djelibeybi/lifx-async/commit/10e008983ffd8b233dd2427a4a4f64661c8f14bd))
+
+
 ## v4.5.0 (2025-12-08)
 
 ### Features

{lifx_async-4.5.0 → lifx_async-4.5.1}/docs/user-guide/advanced-usage.md

@@ -119,6 +119,12 @@ async def use_cached_or_fetch():
 - `MatrixLight.device_chain` - Details of each tile on the chain
 - `MatrixLight.tile_effect` - Either MORPH, FLAME, SKY or OFF
 
+#### CeilingLight properties:
+
+- `CeilingLight.uplight_zone` - Zone index of the uplight component
+- `CeilingLight.downlight_zones` - Slice representing downlight zones
+- `CeilingLight.uplight_is_on` - True if uplight has brightness > 0 (requires recent data)
+- `CeilingLight.downlight_is_on` - True if any downlight zone has brightness > 0 (requires recent data)
 
 **Note**: Volatile state properties (power, color, hev_cycle, zones, tile_colors) have been removed. Always use `get_*()` methods to fetch these values from devices as they change too frequently to benefit from caching.
 

lifx_async-4.5.1/docs/user-guide/ceiling-lights.md

@@ -0,0 +1,293 @@
+# Ceiling Lights
+
+LIFX Ceiling lights are unique fixtures that combine two lighting components in one device:
+
+- **Downlight**: Main illumination with multiple addressable zones (63 or 127 zones)
+- **Uplight**: Ambient/indirect lighting via a single zone
+
+The `CeilingLight` class provides high-level control over these components while inheriting full matrix functionality from `MatrixLight`.
+
+## Supported Devices
+
+| Product | Zones | Layout |
+|---------|-------|--------|
+| LIFX Ceiling (US/Intl) | 64 | 8x8 grid, zone 63 = uplight |
+| LIFX Ceiling Capsule (US/Intl) | 128 | 16x8 grid, zone 127 = uplight |
+
+## Quick Start
+
+```python
+from lifx import CeilingLight
+from lifx.color import HSBK
+
+async def main():
+    async with await CeilingLight.from_ip("192.168.1.100") as ceiling:
+        # Set downlight to warm white
+        await ceiling.set_downlight_colors(
+            HSBK(hue=0, saturation=0, brightness=1.0, kelvin=3000)
+        )
+
+        # Set uplight to a dim, warm ambient glow
+        await ceiling.set_uplight_color(
+            HSBK(hue=30, saturation=0.2, brightness=0.3, kelvin=2700)
+        )
+```
+
+## Component Control
+
+### Setting Colors
+
+#### Downlight
+
+Set all downlight zones to the same color:
+
+```python
+# Single color for all zones
+await ceiling.set_downlight_colors(
+    HSBK(hue=0, saturation=0, brightness=0.8, kelvin=4000)
+)
+```
+
+Or set each zone individually:
+
+```python
+# Create a gradient across all zones
+zone_count = len(range(*ceiling.downlight_zones.indices(256)))
+colors = [
+    HSBK(hue=(i * 360 / zone_count), saturation=1.0, brightness=0.5, kelvin=3500)
+    for i in range(zone_count)
+]
+await ceiling.set_downlight_colors(colors)
+```
+
+#### Uplight
+
+```python
+await ceiling.set_uplight_color(
+    HSBK(hue=30, saturation=0.1, brightness=0.4, kelvin=2700)
+)
+```
+
+### Reading Current Colors
+
+```python
+# Get current uplight color
+uplight_color = await ceiling.get_uplight_color()
+print(f"Uplight: H={uplight_color.hue}, B={uplight_color.brightness}")
+
+# Get all downlight colors
+downlight_colors = await ceiling.get_downlight_colors()
+print(f"Downlight zones: {len(downlight_colors)}")
+```
+
+### Turning Components On/Off
+
+The `turn_*_on()` and `turn_*_off()` methods provide smart state management:
+
+```python
+# Turn off uplight (stores current color for later restoration)
+await ceiling.turn_uplight_off()
+
+# Turn uplight back on (restores previous color)
+await ceiling.turn_uplight_on()
+
+# Turn on with a specific color
+await ceiling.turn_uplight_on(
+    color=HSBK(hue=0, saturation=0, brightness=1.0, kelvin=3500)
+)
+```
+
+The same pattern works for downlights:
+
+```python
+# Turn off downlight
+await ceiling.turn_downlight_off()
+
+# Turn downlight back on
+await ceiling.turn_downlight_on()
+
+# Turn on with specific colors
+await ceiling.turn_downlight_on(
+    colors=HSBK(hue=0, saturation=0, brightness=0.8, kelvin=4000)
+)
+```
+
+### Checking Component State
+
+```python
+# Check if components are on
+if ceiling.uplight_is_on:
+    print("Uplight is on")
+
+if ceiling.downlight_is_on:
+    print("Downlight is on")
+```
+
+!!! note "State Properties Require Recent Data"
+    The `uplight_is_on` and `downlight_is_on` properties rely on cached data.
+    Call `get_uplight_color()` or `get_downlight_colors()` first to ensure
+    accurate state.
+
+## Zone Layout
+
+Access the component zone indices directly:
+
+```python
+async with await CeilingLight.from_ip("192.168.1.100") as ceiling:
+    # Get uplight zone index (63 or 127 depending on model)
+    uplight_idx = ceiling.uplight_zone
+    print(f"Uplight zone: {uplight_idx}")
+
+    # Get downlight zones as a slice
+    downlight_slice = ceiling.downlight_zones
+    print(f"Downlight zones: {downlight_slice}")  # slice(0, 63) or slice(0, 127)
+
+    # Calculate number of downlight zones
+    zone_count = len(range(*downlight_slice.indices(256)))
+    print(f"Number of downlight zones: {zone_count}")
+```
+
+## State Persistence
+
+CeilingLight supports optional state persistence to preserve component colors across sessions:
+
+```python
+async with await CeilingLight.from_ip(
+    "192.168.1.100",
+    state_file="~/.lifx/ceiling_state.json"
+) as ceiling:
+    # Colors are automatically loaded from file on connection
+    # and saved when using turn_*_off() methods
+
+    await ceiling.turn_uplight_off()  # Saves current color to file
+    # ... later ...
+    await ceiling.turn_uplight_on()   # Restores from file if available
+```
+
+The state file stores colors per device serial number, supporting multiple devices:
+
+```json
+{
+  "d073d5123456": {
+    "uplight": {
+      "hue": 30.0,
+      "saturation": 0.2,
+      "brightness": 0.4,
+      "kelvin": 2700
+    },
+    "downlight": [
+      {"hue": 0.0, "saturation": 0.0, "brightness": 0.8, "kelvin": 4000}
+    ]
+  }
+}
+```
+
+## Brightness Determination
+
+When calling `turn_uplight_on()` or `turn_downlight_on()` without a color parameter, CeilingLight uses the following priority to determine brightness:
+
+1. **Stored state**: If a color was previously saved (via `turn_*_off()` or `set_*_color()`)
+2. **Infer from other component**: Average brightness of the other component
+3. **Default**: 80% brightness
+
+This ensures a reasonable brightness level even when no state is available.
+
+## Transition Duration
+
+All color-setting methods support smooth transitions:
+
+```python
+# 2-second transition to new color
+await ceiling.set_uplight_color(
+    HSBK(hue=0, saturation=0, brightness=1.0, kelvin=3500),
+    duration=2.0  # seconds
+)
+
+# Instant change (default)
+await ceiling.set_downlight_colors(
+    HSBK(hue=240, saturation=1.0, brightness=0.5, kelvin=3500),
+    duration=0.0
+)
+```
+
+## MatrixLight Compatibility
+
+CeilingLight extends `MatrixLight`, so all matrix operations are available:
+
+```python
+async with await CeilingLight.from_ip("192.168.1.100") as ceiling:
+    # Use MatrixLight methods directly
+    all_colors = await ceiling.get_all_tile_colors()
+    tile_chain = await ceiling.get_tile_chain()
+
+    # Set raw matrix colors (bypasses component abstraction)
+    await ceiling.set_matrix_colors(0, colors)
+
+    # Apply effects
+    from lifx.protocol.protocol_types import TileEffectType
+    await ceiling.set_tile_effect(
+        effect_type=TileEffectType.MORPH,
+        speed=5000,
+    )
+```
+
+## Example: Night Mode
+
+Create a subtle night light with dim uplight and downlight off:
+
+```python
+from lifx import CeilingLight
+from lifx.color import HSBK
+
+async def night_mode(ip: str):
+    async with await CeilingLight.from_ip(ip) as ceiling:
+        # Store current colors before turning off
+        await ceiling.turn_downlight_off()
+
+        # Set uplight to very dim warm glow
+        await ceiling.set_uplight_color(
+            HSBK(hue=30, saturation=0.3, brightness=0.05, kelvin=2200),
+            duration=2.0
+        )
+```
+
+## Example: Daytime Productivity
+
+Bright, cool white for focus:
+
+```python
+async def daytime_mode(ip: str):
+    async with await CeilingLight.from_ip(ip) as ceiling:
+        # Bright cool downlight for task lighting
+        await ceiling.set_downlight_colors(
+            HSBK(hue=0, saturation=0, brightness=1.0, kelvin=5500),
+            duration=1.0
+        )
+
+        # Turn off uplight during the day
+        await ceiling.turn_uplight_off(duration=1.0)
+```
+
+## Example: Evening Ambiance
+
+Warm tones with accent uplight:
+
+```python
+async def evening_mode(ip: str):
+    async with await CeilingLight.from_ip(ip) as ceiling:
+        # Dimmed warm downlight
+        await ceiling.set_downlight_colors(
+            HSBK(hue=30, saturation=0.1, brightness=0.4, kelvin=2700),
+            duration=2.0
+        )
+
+        # Colorful uplight accent
+        await ceiling.set_uplight_color(
+            HSBK(hue=280, saturation=0.6, brightness=0.3, kelvin=3500),
+            duration=2.0
+        )
+```
+
+## API Reference
+
+See [CeilingLight API Reference](../api/devices.md#ceiling-light) for complete method documentation.

{lifx_async-4.5.0 → lifx_async-4.5.1}/mkdocs.yml

@@ -130,6 +130,7 @@ plugins:
       - getting-started/effects.md: Light effects and animations
       User Guide:
       - user-guide/themes.md: Working with color themes
+      - user-guide/ceiling-lights.md: Controlling LIFX Ceiling uplight and downlight components
       - user-guide/advanced-usage.md: Advanced usage patterns and best practices
       - user-guide/effects-custom.md: Creating custom light effects
       - user-guide/troubleshooting.md: Common issues and solutions
@@ -199,6 +200,7 @@ nav:
   - Light Effects: getting-started/effects.md
 - User Guide:
   - Themes: user-guide/themes.md
+  - Ceiling Lights: user-guide/ceiling-lights.md
   - Advanced Usage: user-guide/advanced-usage.md
   - Custom Effects: user-guide/effects-custom.md
   - Troubleshooting: user-guide/troubleshooting.md

{lifx_async-4.5.0 → lifx_async-4.5.1}/pyproject.toml

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

{lifx_async-4.5.0 → lifx_async-4.5.1}/src/lifx/__init__.py

@@ -16,6 +16,7 @@ from lifx.api import (
 )
 from lifx.color import HSBK, Colors
 from lifx.devices import (
+    CeilingLight,
     Device,
     DeviceInfo,
     DeviceVersion,
@@ -71,6 +72,7 @@ __all__ = [
     "MultiZoneLightState",
     "MatrixLight",
     "MatrixLightState",
+    "CeilingLight",
     # Color
     "HSBK",
     "Colors",

{lifx_async-4.5.0 → lifx_async-4.5.1}/src/lifx/devices/matrix.py

@@ -354,10 +354,7 @@ class MatrixLight(Light):
     def __init__(self, *args, **kwargs) -> None:
         """Initialize MatrixLight device.
 
-        Args:
-            serial: Device serial number
-            ip: Device IP address
-            port: Device port (default: 56700)
+        See :class:`Light` for parameter documentation.
         """
         super().__init__(*args, **kwargs)
         # Matrix specific properties