hue-entertainment-pykit 0.9.4__tar.gz

hue_entertainment_pykit-0.9.4/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Dominik Hrdas
+
+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.

hue_entertainment_pykit-0.9.4/PKG-INFO

@@ -0,0 +1,186 @@
+Metadata-Version: 2.4
+Name: hue-entertainment-pykit
+Version: 0.9.4
+Summary: A comprehensive Python toolkit for Philips Hue Entertainment API
+Author: Dominik Hrdas
+License-Expression: MIT
+Project-URL: Repository, https://github.com/hrdasdominik/hue-entertainment-pykit
+Keywords: philips,hue,lights,entertainment,api
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Utilities
+Requires-Python: <3.13,>=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Requires-Dist: python-mbedtls<3,>=2.10.1
+Requires-Dist: requests<3,>=2.32.5
+Requires-Dist: typing_extensions<5,>=4.8.0; python_version < "3.11"
+Requires-Dist: zeroconf<1,>=0.148.0
+Provides-Extra: dev
+Requires-Dist: flake8<8,>=7; extra == "dev"
+Requires-Dist: pylint<5,>=4; extra == "dev"
+Dynamic: license-file
+
+# Hue Entertainment PyKit
+![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/hrdasdominik/hue-entertainment-pykit/python-app.yml?branch=main&label=main)
+![GitHub Tag](https://img.shields.io/github/v/tag/hrdasdominik/hue-entertainment-pykit?include_prereleases)
+![Python Version from PEP 621 TOML](https://img.shields.io/python/required-version-toml?tomlFilePath=https%3A%2F%2Fraw.githubusercontent.com%2Fhrdasdominik%2Fhue-entertainment-pykit%2Fmain%2Fpyproject.toml)
+![PyPI - Version](https://img.shields.io/pypi/v/hue-entertainment-pykit?link=https%3A%2F%2Fpypi.org%2Fproject%2Fhue-entertainment-pykit%2F)
+![PyPI - License](https://img.shields.io/pypi/l/hue-entertainment-pykit?link=https%3A%2F%2Fpypi.org%2Fproject%2Fhue-entertainment-pykit%2F)
+
+
+
+<img align="right" alt="HEPK logo" src="docs/logo/horizontal.png" width="400">
+
+## Introduction
+
+Unlock the full spectrum of Philips Hue lighting with the Hue Entertainment PyKit. This Python library simplifies connecting to the Hue Bridge and controlling lights with minimal latency, empowering developers to create dynamic and responsive lighting environments.
+
+---
+
+## Motivation
+
+Confronted with the complexity of the official Hue EDK and challenges in DTLS handshake implementation which many in the community had, Hue Entertainment PyKit was crafted to provide a straightforward, Python-centric approach to light control using the Philips Hue Entertainment API.
+
+---
+
+## Quick Start
+
+### Installing
+
+To install Hue Entertainment PyKit, ensure you have Python installed on your system, and then run the following command:
+```sh
+pip install hue-entertainment-pykit
+```
+
+__Note:__ Python 3.13 and later are currently unsupported due to ___python-mbedtls___ not yet providing compatible 
+wheels. This sucks cause last update was in second quarter of 2024 and it looks like there won't be any anymore.
+
+---
+
+## Usage
+
+To interact with your Philips Hue lights you can do:
+
+### Logging Configuration (Optional)
+
+Hue Entertainment PyKit configures logging **only for its own logger namespace**
+(`hue_entertainment_pykit.*`). It does not modify the root logger.
+
+```python
+import logging
+from hue_entertainment_pykit import setup_logs
+
+# Enable library logging with the default formatter and handlers
+setup_logs()
+
+# Or customize the logging level (e.g., exclude DEBUG messages)
+setup_logs(level=logging.INFO)
+
+# You can also further customize logging by specifying the maximum log file size and the number of backup files
+setup_logs(level=logging.INFO, max_file_size=1024 * 1024, backup_count=1)
+
+# Each parameter is optional and comes with predefined default values
+```
+
+To log messages from your own application code in the same format, use a
+named logger under the same namespace:
+
+```python
+import logging
+
+logger = logging.getLogger("hue_entertainment_pykit.example")
+logger.info("Example started")
+```
+
+If you prefer to use logging.info(...) (root logger), configure it separately:
+
+```python
+import logging
+logging.basicConfig(level=logging.INFO)
+```
+
+#### Silencing noisy third-party logs
+
+Some dependencies (e.g. `urllib3`, `zeroconf`) may emit verbose DEBUG logs if
+root logging is enabled. You can reduce noise like this:
+
+```python
+import logging
+
+logging.getLogger("urllib3").setLevel(logging.WARNING)
+logging.getLogger("zeroconf").setLevel(logging.WARNING)
+```
+
+### Discovery (Optional)
+
+Use only on your Local Area Network (LAN) to discover and fetch all Bridges that can be used then for streaming
+
+```python
+from hue_entertainment_pykit import Discovery
+
+discovery = Discovery()
+
+# returns dict[str, Bridge] where the key is name of the bridge and value is the Bridge model with all important info for connecting to Entertainment API
+bridges = discovery.discover_bridges()  
+```
+### Streaming
+
+The Streaming service in Hue Entertainment PyKit provides thread-safe communication with Hue lights, ensuring smooth and uninterrupted interactions. To prevent connection timeouts, the service implements a keep-alive feature: if no command is sent for 9.5 seconds, the last message is automatically resent to maintain the connection.
+
+Below is a streamlined example to set up and manage your streaming session:
+
+```python
+import time
+from hue_entertainment_pykit import create_bridge, Entertainment, Streaming
+
+# Set up the Bridge instance with the all needed configuration
+bridge = create_bridge(
+    identification="4abb74df-5b6b-410e-819b-bf4448355dff",
+    rid="d476df48-83ad-4430-a104-53c30b46b4d0",
+    ip_address="192.168.1.100",
+    swversion=1962097030,
+    username="8nuTIcK2nOf5oi88-5zPvV1YCt0wTHZIGG8MwXpu",
+    hue_app_id="94530efc-933a-4f7c-97e5-ccf1a9fc79af",
+    clientkey="B42753E1E1605A1AB90E1B6A0ECF9C51",
+    name="1st Bridge"
+)
+
+# Set up the Entertainment API service
+entertainment_service = Entertainment(bridge)
+
+# Fetch all Entertainment Configurations on the Hue bridge
+entertainment_configs = entertainment_service.get_entertainment_configs()
+
+# Add some Entertainment Area selection logic
+# For the purposes of example I'm going to do manual selection
+entertainment_config = list(entertainment_configs.values())[0]
+
+# Set up the Streaming service
+streaming = Streaming(
+    bridge, entertainment_config, entertainment_service.get_ent_conf_repo()
+)
+
+# Start streaming messages to the bridge
+streaming.start_stream()
+
+# Set the color space to xyb or rgb
+streaming.set_color_space("xyb")
+
+# Set input commands for the lights
+# First three values in the tuple are placeholders for the color RGB8(int) or (in this case) XYB(float) and the last integer is light ID inside the Entertainment API
+streaming.set_input((0.0, 0.63435, 0.3, 0))  # Light command for the first light
+streaming.set_input((0.63435, 0.0, 0.3, 1))  # Light command for the second light
+# ... Add more inputs as needed for additional lights and logic
+
+# For the purpose of example sleep is used for all inputs to process before stop_stream is called
+# Inputs are set inside Event queue meaning they're on another thread so user can interact with application continuously
+time.sleep(0.1)
+
+# Stop the streaming session
+streaming.stop_stream()
+```
+
+Replace the placeholders in the `set_input` method with actual light IDs and the color and brightness values you intend to use. The `start_stream` method initiates the streaming session, `set_color_space` configures the color space, and `stop_stream` terminates the session.

hue_entertainment_pykit-0.9.4/README.md

@@ -0,0 +1,161 @@
+# Hue Entertainment PyKit
+![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/hrdasdominik/hue-entertainment-pykit/python-app.yml?branch=main&label=main)
+![GitHub Tag](https://img.shields.io/github/v/tag/hrdasdominik/hue-entertainment-pykit?include_prereleases)
+![Python Version from PEP 621 TOML](https://img.shields.io/python/required-version-toml?tomlFilePath=https%3A%2F%2Fraw.githubusercontent.com%2Fhrdasdominik%2Fhue-entertainment-pykit%2Fmain%2Fpyproject.toml)
+![PyPI - Version](https://img.shields.io/pypi/v/hue-entertainment-pykit?link=https%3A%2F%2Fpypi.org%2Fproject%2Fhue-entertainment-pykit%2F)
+![PyPI - License](https://img.shields.io/pypi/l/hue-entertainment-pykit?link=https%3A%2F%2Fpypi.org%2Fproject%2Fhue-entertainment-pykit%2F)
+
+
+
+<img align="right" alt="HEPK logo" src="docs/logo/horizontal.png" width="400">
+
+## Introduction
+
+Unlock the full spectrum of Philips Hue lighting with the Hue Entertainment PyKit. This Python library simplifies connecting to the Hue Bridge and controlling lights with minimal latency, empowering developers to create dynamic and responsive lighting environments.
+
+---
+
+## Motivation
+
+Confronted with the complexity of the official Hue EDK and challenges in DTLS handshake implementation which many in the community had, Hue Entertainment PyKit was crafted to provide a straightforward, Python-centric approach to light control using the Philips Hue Entertainment API.
+
+---
+
+## Quick Start
+
+### Installing
+
+To install Hue Entertainment PyKit, ensure you have Python installed on your system, and then run the following command:
+```sh
+pip install hue-entertainment-pykit
+```
+
+__Note:__ Python 3.13 and later are currently unsupported due to ___python-mbedtls___ not yet providing compatible 
+wheels. This sucks cause last update was in second quarter of 2024 and it looks like there won't be any anymore.
+
+---
+
+## Usage
+
+To interact with your Philips Hue lights you can do:
+
+### Logging Configuration (Optional)
+
+Hue Entertainment PyKit configures logging **only for its own logger namespace**
+(`hue_entertainment_pykit.*`). It does not modify the root logger.
+
+```python
+import logging
+from hue_entertainment_pykit import setup_logs
+
+# Enable library logging with the default formatter and handlers
+setup_logs()
+
+# Or customize the logging level (e.g., exclude DEBUG messages)
+setup_logs(level=logging.INFO)
+
+# You can also further customize logging by specifying the maximum log file size and the number of backup files
+setup_logs(level=logging.INFO, max_file_size=1024 * 1024, backup_count=1)
+
+# Each parameter is optional and comes with predefined default values
+```
+
+To log messages from your own application code in the same format, use a
+named logger under the same namespace:
+
+```python
+import logging
+
+logger = logging.getLogger("hue_entertainment_pykit.example")
+logger.info("Example started")
+```
+
+If you prefer to use logging.info(...) (root logger), configure it separately:
+
+```python
+import logging
+logging.basicConfig(level=logging.INFO)
+```
+
+#### Silencing noisy third-party logs
+
+Some dependencies (e.g. `urllib3`, `zeroconf`) may emit verbose DEBUG logs if
+root logging is enabled. You can reduce noise like this:
+
+```python
+import logging
+
+logging.getLogger("urllib3").setLevel(logging.WARNING)
+logging.getLogger("zeroconf").setLevel(logging.WARNING)
+```
+
+### Discovery (Optional)
+
+Use only on your Local Area Network (LAN) to discover and fetch all Bridges that can be used then for streaming
+
+```python
+from hue_entertainment_pykit import Discovery
+
+discovery = Discovery()
+
+# returns dict[str, Bridge] where the key is name of the bridge and value is the Bridge model with all important info for connecting to Entertainment API
+bridges = discovery.discover_bridges()  
+```
+### Streaming
+
+The Streaming service in Hue Entertainment PyKit provides thread-safe communication with Hue lights, ensuring smooth and uninterrupted interactions. To prevent connection timeouts, the service implements a keep-alive feature: if no command is sent for 9.5 seconds, the last message is automatically resent to maintain the connection.
+
+Below is a streamlined example to set up and manage your streaming session:
+
+```python
+import time
+from hue_entertainment_pykit import create_bridge, Entertainment, Streaming
+
+# Set up the Bridge instance with the all needed configuration
+bridge = create_bridge(
+    identification="4abb74df-5b6b-410e-819b-bf4448355dff",
+    rid="d476df48-83ad-4430-a104-53c30b46b4d0",
+    ip_address="192.168.1.100",
+    swversion=1962097030,
+    username="8nuTIcK2nOf5oi88-5zPvV1YCt0wTHZIGG8MwXpu",
+    hue_app_id="94530efc-933a-4f7c-97e5-ccf1a9fc79af",
+    clientkey="B42753E1E1605A1AB90E1B6A0ECF9C51",
+    name="1st Bridge"
+)
+
+# Set up the Entertainment API service
+entertainment_service = Entertainment(bridge)
+
+# Fetch all Entertainment Configurations on the Hue bridge
+entertainment_configs = entertainment_service.get_entertainment_configs()
+
+# Add some Entertainment Area selection logic
+# For the purposes of example I'm going to do manual selection
+entertainment_config = list(entertainment_configs.values())[0]
+
+# Set up the Streaming service
+streaming = Streaming(
+    bridge, entertainment_config, entertainment_service.get_ent_conf_repo()
+)
+
+# Start streaming messages to the bridge
+streaming.start_stream()
+
+# Set the color space to xyb or rgb
+streaming.set_color_space("xyb")
+
+# Set input commands for the lights
+# First three values in the tuple are placeholders for the color RGB8(int) or (in this case) XYB(float) and the last integer is light ID inside the Entertainment API
+streaming.set_input((0.0, 0.63435, 0.3, 0))  # Light command for the first light
+streaming.set_input((0.63435, 0.0, 0.3, 1))  # Light command for the second light
+# ... Add more inputs as needed for additional lights and logic
+
+# For the purpose of example sleep is used for all inputs to process before stop_stream is called
+# Inputs are set inside Event queue meaning they're on another thread so user can interact with application continuously
+time.sleep(0.1)
+
+# Stop the streaming session
+streaming.stop_stream()
+```
+
+Replace the placeholders in the `set_input` method with actual light IDs and the color and brightness values you intend to use. The `start_stream` method initiates the streaming session, `set_color_space` configures the color space, and `stop_stream` terminates the session.

hue_entertainment_pykit-0.9.4/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["setuptools>=75.2.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "hue-entertainment-pykit"
+version = "0.9.4"
+authors = [
+    {name = "Dominik Hrdas"}
+]
+description = "A comprehensive Python toolkit for Philips Hue Entertainment API"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE.md"]
+classifiers = [
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Operating System :: OS Independent",
+    "Topic :: Utilities"
+]
+requires-python = ">=3.10, <3.13"
+dependencies = [
+    "python-mbedtls>=2.10.1, <3",
+    "requests>=2.32.5, <3",
+    "typing_extensions>=4.8.0, <5; python_version < '3.11'",
+    "zeroconf>=0.148.0, <1"
+]
+keywords = ["philips", "hue", "lights", "entertainment", "api"]
+
+[project.optional-dependencies]
+dev = [
+    "flake8>=7, <8",
+    "pylint>=4, <5"
+]
+
+[project.urls]
+Repository = "https://github.com/hrdasdominik/hue-entertainment-pykit"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]

hue_entertainment_pykit-0.9.4/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

hue_entertainment_pykit-0.9.4/src/hue_entertainment_pykit/__init__.py

@@ -0,0 +1,36 @@
+"""
+The `hue_entertainment_pykit` module offers a suite of tools designed to interface with
+Philips Hue Entertainment capabilities. It provides high-level abstractions to discover and interact with Hue bridges,
+manage entertainment configurations, and create responsive lighting experiences.
+
+Available Classes and Functions:
+- `Discovery`: A utility class to discover Hue bridges on the local network. It simplifies the process of finding and
+connecting to available Hue bridges without needing to deal with network details.
+- `Streaming`: Facilitates the creation of entertainment sessions, allowing for the control of Hue lights in real-time
+for dynamic lighting effects synchronized with media or games.
+- `create_bridge`: A factory function to instantiate a `Bridge` object, which represents a physical Hue bridge device
+and serves as the central point of communication with the Hue system.
+- `Bridge`: Represents a Philips Hue bridge. It provides methods to interact with the bridge, such as authenticating,
+sending commands, and querying for connected lights and sensors.
+- `EntertainmentConfiguration`: Encapsulates the configuration necessary for setting up entertainment areas,
+defining which lights are used, and how they react during an entertainment session.
+- `setup_logs`: Simplifies the logging setup process for the entire package, allowing for easy initialization of
+logging with customizable settings for file size, backup counts, and log levels.
+
+This module abstracts the complexities involved in directly handling the Hue Entertainment API and provides a
+streamlined interface for building applications that can create immersive lighting experiences.
+"""
+
+from .api import Discovery, Streaming, create_bridge, setup_logs, Entertainment
+from .models.bridge import Bridge
+from .models.entertainment_configuration import EntertainmentConfiguration
+
+__all__ = [
+    "Discovery",
+    "Streaming",
+    "create_bridge",
+    "setup_logs",
+    "Bridge",
+    "EntertainmentConfiguration",
+    "Entertainment",
+]