phue2 0.0.1.dev279__py3-none-any.whl

phue2/sensor.py

@@ -0,0 +1,307 @@
+"""Sensor classes for interacting with Philips Hue sensors."""
+
+import logging
+from collections import UserDict
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any, TypeAlias
+
+if TYPE_CHECKING:
+    from phue2 import Bridge
+
+logger = logging.getLogger("phue_modern")
+
+SensorData: TypeAlias = dict[str, Any]
+
+
+class _SensorDataWrapper(UserDict[str, Any]):
+    """
+    Base class for Sensor State/Config wrappers using UserDict.
+    Updates the bridge when an item is set.
+    Holds a cached view of the state/config.
+    """
+
+    # UserDict stores data in the 'data' attribute (which is a dict)
+    data: SensorData
+
+    def __init__(
+        self, bridge: "Bridge", sensor_id: int, initial_data: SensorData | None = None
+    ):
+        super().__init__(initial_data or {})
+        self._bridge = bridge
+        self._sensor_id = sensor_id
+        # Store the method responsible for updating the bridge (state or config)
+        self._update_bridge_method: Callable[[int, SensorData], Any] = (
+            self._get_bridge_update_method()
+        )
+
+    def _get_bridge_update_method(self) -> Callable[[int, SensorData], Any]:
+        # This method should be implemented by subclasses
+        raise NotImplementedError
+
+    def __setitem__(self, key: str, value: Any) -> None:
+        """Sets an item locally and updates the bridge."""
+        # Optional: Check if the value is actually changing to avoid unnecessary API calls
+        if key in self.data and self.data[key] == value:
+            logger.debug(
+                f"Skipping bridge update for sensor {self._sensor_id}: key '{key}' value unchanged."
+            )
+            return
+
+        # Update local cache *before* calling the bridge
+        # If the bridge call fails, the local cache reflects the intended state.
+        # Alternatively, update after bridge call succeeds if you want cache
+        # to always reflect confirmed bridge state. Let's update before for responsiveness.
+        super().__setitem__(key, value)
+
+        # Update the bridge with *only the changed key/value pair*
+        update_payload = {key: value}
+        try:
+            logger.debug(
+                f"Updating bridge for sensor {self._sensor_id}: {update_payload}"
+            )
+            self._update_bridge_method(self._sensor_id, update_payload)
+        except Exception as e:
+            # Handle potential API errors (e.g., network issues, invalid key/value)
+            logger.error(
+                f"Failed to update bridge for sensor {self._sensor_id} with {update_payload}: {e}"
+            )
+            # Optional: Revert local change if bridge update fails?
+            # Depends on desired behavior. For now, keep local change.
+            # Consider raising the exception or providing feedback.
+            # For simplicity here, we just log the error.
+
+    def update(self, *args: Any, **kwargs: Any) -> None:
+        """
+        Updates the dictionary with multiple items.
+        Calls the bridge update method for each changed item individually.
+        Note: This may result in multiple API calls. If the bridge API supports
+        updating multiple keys in one call, this could be optimized.
+        """
+        # UserDict.update handles merging args and kwargs into self.data
+        # We need to intercept this to call the bridge for each change.
+        temp_dict = dict(*args, **kwargs)
+        for key, value in temp_dict.items():
+            # This will call our overridden __setitem__, which handles bridge update
+            self[key] = value
+
+    def sync_from_bridge_data(self, data: SensorData) -> None:
+        """
+        Updates the local cache directly from data fetched from the bridge,
+        bypassing the bridge update mechanism (__setitem__).
+        """
+        # Use super().update to modify self.data directly without triggering __setitem__
+        self.data.clear()
+        self.data.update(data)
+        # Alternatively: super().update(data) if you want to merge instead of replace.
+        # Clearing first ensures the cache exactly matches the fetched data.
+
+
+class SensorState(_SensorDataWrapper):
+    """
+    State of a Hue sensor. Updates bridge state on item set.
+    Provides a dictionary-like interface to a cached view of the sensor state.
+    """
+
+    def _get_bridge_update_method(self):
+        return self._bridge.set_sensor_state
+
+
+class SensorConfig(_SensorDataWrapper):
+    """
+    Configuration of a Hue sensor. Updates bridge config on item set.
+    Provides a dictionary-like interface to a cached view of the sensor config.
+    """
+
+    def _get_bridge_update_method(self):
+        return self._bridge.set_sensor_config
+
+
+class Sensor:
+    """
+    Hue Sensor object.
+
+    Provides access to sensor properties, state, and configuration.
+    State and config are cached locally. Modifying `sensor.state['key'] = value`
+    or `sensor.config['key'] = value` will update the bridge.
+    Call `sensor.refresh()` to update the local cache from the bridge.
+    """
+
+    # Type hint for the bridge reference
+    bridge: "Bridge"
+    sensor_id: int
+
+    # Private attributes for caching
+    # Use Optional[T] and initialize to None to indicate they haven't been fetched yet.
+    _raw_data: SensorData | None = None
+    _state: SensorState
+    _config: SensorConfig
+    # Cache basic attributes to avoid repeated parsing/dict access
+    _name: str | None = None
+    _modelid: str | None = None
+    _swversion: str | None = None
+    _type: str | None = None
+    _uniqueid: str | None = None
+    _manufacturername: str | None = None
+    _recycle: bool | None = None
+
+    def __init__(self, bridge: "Bridge", sensor_id: int):
+        self.bridge = bridge
+        self.sensor_id = sensor_id
+
+        # Initialize state and config wrappers without initial data.
+        # Data will be populated by refresh() or on first access.
+        self._state = SensorState(bridge, sensor_id)
+        self._config = SensorConfig(bridge, sensor_id)  # Use SensorConfig
+
+    def __repr__(self) -> str:
+        # Fetch name for repr if not already cached. Handle potential errors.
+        try:
+            name = self.name  # Use the property to ensure data is loaded
+        except Exception:
+            name = f"ID {self.sensor_id}"  # Fallback if name fetch fails
+        return f'<{self.__class__.__module__}.{self.__class__.__name__} object "{name}" at {hex(id(self))}>'
+
+    def refresh(self) -> None:
+        """Fetches the latest data from the bridge and updates the local cache."""
+        logger.debug(f"Refreshing data for sensor {self.sensor_id}")
+        try:
+            # Assume bridge.get_sensor(id) returns the full sensor dictionary
+            self._raw_data = self.bridge.get_sensor(self.sensor_id)
+            if not isinstance(self._raw_data, dict):
+                raise TypeError(
+                    f"Expected dict from bridge.get_sensor, got {type(self._raw_data)}"
+                )
+        except Exception as e:
+            logger.error(f"Failed to refresh data for sensor {self.sensor_id}: {e}")
+            # Keep stale data or clear it? Let's keep stale data and log error.
+            # self._raw_data = None # Option: clear cache on failure
+            raise  # Re-raise the exception so the caller knows refresh failed
+
+        # Update cached attributes directly from raw data
+        self._name = self._raw_data.get("name")
+        self._modelid = self._raw_data.get("modelid")
+        self._swversion = self._raw_data.get("swversion")
+        self._type = self._raw_data.get("type")
+        self._uniqueid = self._raw_data.get("uniqueid")
+        self._manufacturername = self._raw_data.get("manufacturername")
+        self._recycle = self._raw_data.get("recycle")
+
+        # Update state and config caches using the sync method (avoids bridge writes)
+        self._state.sync_from_bridge_data(self._raw_data.get("state", {}))
+        self._config.sync_from_bridge_data(self._raw_data.get("config", {}))
+        logger.debug(f"Sensor {self.sensor_id} data refreshed successfully.")
+
+    def _ensure_data(self) -> None:
+        """Ensures sensor data has been fetched at least once, calling refresh() if needed."""
+        if self._raw_data is None:
+            logger.debug(f"Initial data fetch for sensor {self.sensor_id}")
+            self.refresh()  # This will fetch and populate everything
+
+    # --- Properties ---
+
+    @property
+    def name(self) -> str:
+        """Get or set the name of the sensor [string]. Fetches data on first access."""
+        self._ensure_data()
+        # Provide a default/fallback if name is somehow missing after refresh
+        return self._name or f"Sensor {self.sensor_id}"
+
+    @name.setter
+    def name(self, value: str) -> None:
+        if not isinstance(value, str):  # type: ignore[unnecessary-isinstance]
+            raise TypeError("Sensor name must be a string")
+
+        # Get the current name (ensures data is loaded if it wasn't already)
+        old_name = self.name
+        if old_name == value:
+            return  # No change needed
+
+        logger.debug(
+            f"Attempting to rename sensor {self.sensor_id} from '{old_name}' to '{value}'"
+        )
+        try:
+            # Use bridge.set_sensor for top-level attributes like name
+            self.bridge.set_sensor(self.sensor_id, {"name": value})
+        except Exception as e:
+            logger.error(
+                f"Failed to set name for sensor {self.sensor_id} via bridge: {e}"
+            )
+            raise  # Re-raise exception
+
+        # Update local cache only after successful bridge call
+        self._name = value
+        if self._raw_data:  # Update raw data cache if it exists
+            self._raw_data["name"] = value
+
+        # Update bridge's name lookup cache (if it exists and is used)
+        if hasattr(self.bridge, "sensors_by_name"):
+            # Be careful modifying another object's state directly
+            # Ensure this is the intended interaction pattern with the Bridge class
+            if old_name in self.bridge.sensors_by_name:
+                del self.bridge.sensors_by_name[old_name]
+            self.bridge.sensors_by_name[value] = self
+        logger.info(f"Sensor {self.sensor_id} renamed to '{value}'")
+
+    # Read-only properties using the cache
+    @property
+    def modelid(self) -> str | None:
+        """Get hardware model ID [string, read-only]. Fetches data on first access."""
+        self._ensure_data()
+        return self._modelid
+
+    @property
+    def swversion(self) -> str | None:
+        """Get firmware version [string, read-only]. Fetches data on first access."""
+        self._ensure_data()
+        return self._swversion
+
+    @property
+    def type(self) -> str | None:
+        """Get sensor type [string, read-only]. Fetches data on first access."""
+        self._ensure_data()
+        return self._type
+
+    @property
+    def uniqueid(self) -> str | None:
+        """Get unique device ID [string, read-only]. Fetches data on first access."""
+        self._ensure_data()
+        return self._uniqueid
+
+    @property
+    def manufacturername(self) -> str | None:
+        """Get manufacturer name [string, read-only]. Fetches data on first access."""
+        self._ensure_data()
+        return self._manufacturername
+
+    @property
+    def recycle(self) -> bool | None:
+        """Check if resource should be auto-removed [bool, read-only]. Fetches data on first access."""
+        self._ensure_data()
+        return self._recycle
+
+    # State and Config properties return the cached wrapper objects
+    @property
+    def state(self) -> SensorState:
+        """
+        Get the cached state of the sensor [SensorState].
+        Modifying items (e.g., `sensor.state['on'] = True`) updates the bridge.
+        Call `sensor.refresh()` to sync cache from the bridge.
+        Fetches data on first access.
+        """
+        self._ensure_data()
+        return self._state
+
+    # Removed state.setter - modifications happen via the returned object
+
+    @property
+    def config(self) -> SensorConfig:
+        """
+        Get the cached config of the sensor [SensorConfig].
+        Modifying items (e.g., `sensor.config['on'] = True`) updates the bridge.
+        Call `sensor.refresh()` to sync cache from the bridge.
+        Fetches data on first access.
+        """
+        self._ensure_data()
+        return self._config
+
+    # Removed config.setter - modifications happen via the returned object

phue2-0.0.1.dev279.dist-info/METADATA

@@ -0,0 +1,188 @@
+Metadata-Version: 2.4
+Name: phue2
+Version: 0.0.1.dev279
+Summary: A Philips Hue Python library
+Author: Nathanaël Lécaudé, Nathan Nowack
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: httpx
+Description-Content-Type: text/markdown
+
+# phue2
+
+modern Python library to control the Philips Hue lighting system
+
+This is a fork of the original [phue library](https://github.com/studioimaginaire/phue) by Nathanaël Lécaudé, modernized with type annotations, improved error handling, and a fully-featured CLI. The library remains MIT licensed.
+
+> [!IMPORTANT]
+
+> I appreciate the original authors work and if there's any interest in merging these (substantial) changes back into the original library, I'm happy to do so.
+
+## Installation
+
+### Using uv
+
+```bash
+uv add phue2
+
+uv pip install phue2
+```
+
+### Using pip
+
+```bash
+pip install phue2
+```
+
+## Repository Structure
+
+```
+.
+├── LICENSE
+├── README.md
+├── examples/
+├── src/
+│   └── phue/
+│       ├── __init__.py
+│       ├── __main__.py      # CLI interface
+│       ├── bridge.py        # Bridge connection handling
+│       ├── exceptions.py    # Custom exceptions
+│       ├── group.py         # Group controls
+│       ├── light.py         # Light controls
+│       ├── scene.py         # Scene handling
+│       └── sensor.py        # Sensor controls
+└── tests/              # Tests
+```
+
+## Requirements
+
+- Python 3.10 or higher (not compatible with Python 2.x)
+- httpx (for network requests)
+
+## Features
+
+- Fully typed with Python type annotations
+- Robust error handling with custom exceptions
+- Comprehensive test suite
+- Colorful, user-friendly command-line interface
+- Support for Lights, Groups, Scenes, and Sensors
+- Auto-discovery of Hue bridges on the network
+- Simple and intuitive API for controlling Hue devices
+
+
+
+## Command Line Usage
+
+The library includes a command-line interface for controlling your Hue lights:
+
+```bash
+# List all lights
+phue ls
+
+# Get details about a specific light
+phue get light "Living Room"
+
+# Turn on a light and set brightness
+phue set light "Kitchen" --on --bri 200
+
+# List all groups
+phue ls groups
+
+# Turn off lights in a group
+phue set group "Downstairs" --off
+```
+
+## Basic Usage
+
+Using the set_light and get_light methods you can control pretty much all the parameters:
+
+```python
+from phue2 import Bridge
+
+# Connect to the bridge
+b = Bridge('192.168.1.100')
+
+# If the app is not registered and the button is not pressed, press the button and call connect()
+# This only needs to be run a single time
+b.connect()
+
+# Get the bridge state (This returns the full dictionary that you can explore)
+b.get_api()
+
+# Prints if light 1 is on or not
+b.get_light(1, 'on')
+
+# Set brightness of lamp 1 to max
+b.set_light(1, 'bri', 254)
+
+# Turn lamp 2 on
+b.set_light(2, 'on', True)
+
+# You can also control multiple lamps by sending a list as lamp_id
+b.set_light([1, 2], 'on', True)
+
+# You can also use light names instead of the id
+b.get_light('Kitchen')
+b.set_light('Kitchen', 'bri', 254)
+
+# Also works with lists
+b.set_light(['Bathroom', 'Garage'], 'on', False)
+```
+
+### Light Objects
+
+If you want to work in a more object-oriented way, you can get Light objects:
+
+```python
+# Get a flat list of light objects
+lights = b.lights
+
+# Print light names
+for light in lights:
+    print(light.name)
+
+# Set brightness of each light to 127
+for light in lights:
+    light.brightness = 127
+
+# Get a dictionary with the light name as the key
+light_names = b.get_light_objects('name')
+
+# Set lights using name as key
+for light_name in ['Kitchen', 'Bedroom', 'Garage']:
+    light = light_names.get(light_name)
+    if light:
+        light.on = True
+        light.hue = 15000
+        light.saturation = 120
+```
+
+## Error Handling
+
+The library provides custom exceptions for better error handling:
+
+```python
+from phue2 import Bridge, PhueRegistrationException, PhueRequestTimeout
+
+try:
+    b = Bridge('192.168.1.100')
+    b.connect()
+except PhueRegistrationException:
+    print("Press the button on the bridge and try again")
+except PhueRequestTimeout:
+    print("Could not connect to the bridge - check your network")
+```
+
+## Acknowledgments
+
+This project is a fork of the original [phue](https://github.com/studioimaginaire/phue) library created by Nathanaël Lécaudé.
+
+The modernized version was created by [zzstoatzz](https://github.com/zzstoatzz) to add type annotations and a more opinionated CLI.
+
+## License
+
+MIT - http://opensource.org/licenses/MIT
+
+"Hue Personal Wireless Lighting" is a trademark owned by Koninklijke Philips Electronics N.V., see www.meethue.com for more information.
+I am in no way affiliated with the Philips organization.

phue2-0.0.1.dev279.dist-info/RECORD

@@ -0,0 +1,15 @@
+phue2/__init__.py,sha256=Uu9QwkzgpJtpWpYEO7MWuAVRPrHclQ7NkbrzKIIyFeU,873
+phue2/__main__.py,sha256=22DGc0YJGxtF5eOQlnYhH29hPLkvh56svKONyqnrTEQ,12987
+phue2/bridge.py,sha256=iFv0pq19bJ3r8El3ZwOzrfac-pls9d8y1PMbxv7cbBg,43862
+phue2/exceptions.py,sha256=tFN3uEkHx2k-oU-wnmg1oKeoZJRrtZSS7L1iep5NHJ8,540
+phue2/group.py,sha256=0ttIZrN-wJPfyXCv9CFxdsJuiYqhiy44gjojeIUI-5A,3995
+phue2/light.py,sha256=BfvsiXUszEHh-1s1n3Nn-cTjiIPpBQ-JNiM-hAqpd5s,10793
+phue2/scene.py,sha256=SB2BTVVS01ytPPvIp8njeXFYCKYi0cZLmxxBdplYKZo,1827
+phue2/sensor.py,sha256=iSe0goDK-xX2AVUJh5Gi60MhKVaylLyMW16l7oEmEpY,12431
+phue2/_internal/__init__.py,sha256=E6FcITKZNPECEK0c0umWMezKBVY6OCDqJpbOkbBfVNw,38
+phue2/_internal/console.py,sha256=nUHNNLUhCAaaBLi82c-gJJXjSFScpFPgZWinxx3JYcs,4853
+phue2-0.0.1.dev279.dist-info/METADATA,sha256=S_QMhD3uo0QqTomtr0NTD21OCIW3cQFhcGiAlireibs,4749
+phue2-0.0.1.dev279.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+phue2-0.0.1.dev279.dist-info/entry_points.txt,sha256=izaWBWq5BqZKkEzL_Cha5PflzTST2vAmGd9NFm-3rk4,45
+phue2-0.0.1.dev279.dist-info/licenses/LICENSE,sha256=53NTqbgURXQ5wulynQxi47i8YBuEcfThsunG4LSJs4s,1080
+phue2-0.0.1.dev279.dist-info/RECORD,,

phue2-0.0.1.dev279.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

phue2-0.0.1.dev279.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+phue = phue2.__main__:main

phue2-0.0.1.dev279.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Nathan Nowack
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.