phue2 0.0.1.dev279__tar.gz

phue2-0.0.1.dev279/.github/workflows/lint.yml

@@ -0,0 +1,36 @@
+name: Lint
+
+on:
+  push:
+    branches: [ master ]
+  pull_request:
+    branches: [ master ]
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          version: "0.6.11"
+
+      - name: Install just
+        uses: extractions/setup-just@v2
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version-file: "pyproject.toml"
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Run pre-commit
+        uses: pre-commit/action@v3.0.1
+        with:
+          extra_args: --all-files

phue2-0.0.1.dev279/.github/workflows/publish.yml

@@ -0,0 +1,26 @@
+name: Publish phue2 to PyPI
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  pypi-publish:
+    name: Upload to PyPI
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: "Install uv"
+        uses: astral-sh/setup-uv@v3
+
+      - name: Build
+        run: uv build --no-cache
+
+      - name: Publish to PyPi
+        run: uv publish -v dist/* --token ${{ secrets.UV_PUBLISH_TOKEN }}

phue2-0.0.1.dev279/.github/workflows/test.yml

@@ -0,0 +1,55 @@
+name: Tests
+
+on:
+  push:
+    branches: [ master ]
+    paths:
+      - "src/**/*.py"
+      - "tests/**/*.py"
+      - "pyproject.toml"
+      - ".github/workflows/test.yml"
+  pull_request:
+    branches: [ master ]
+    paths:
+      - "src/**/*.py"
+      - "tests/**/*.py"
+      - "pyproject.toml"
+      - ".github/workflows/test.yml"
+
+env:
+  # Enable colored output
+  PY_COLORS: 1
+
+jobs:
+  test:
+    name: ${{ matrix.os }} - python:${{ matrix.python-version }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python-version: ["3.10", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          version: "0.6.11"
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install just
+        uses: extractions/setup-just@v2
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Build 
+        run: just build
+
+      - name: Run tests
+        run: just test

phue2-0.0.1.dev279/.gitignore

@@ -0,0 +1,11 @@
+*.pyc
+*~
+*.swp
+test.py
+*.DS_Store
+dist
+MANIFEST
+__pycache__
+.pytest_cache
+.vscode
+.env

phue2-0.0.1.dev279/.pre-commit-config.yaml

@@ -0,0 +1,22 @@
+repos:
+  - repo: https://github.com/astral-sh/uv-pre-commit
+    # uv version.
+    rev: 0.6.11
+    hooks:
+      - id: uv-lock
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    # Ruff version.
+    rev: v0.9.1
+    hooks:
+      # Run the linter.
+      - id: ruff
+        args: [--fix]
+      # Run the formatter.
+      - id: ruff-format
+  - repo: local
+    hooks:
+      - id: typecheck
+        name: typecheck
+        entry: just typecheck
+        language: system
+        pass_filenames: false

phue2-0.0.1.dev279/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.

phue2-0.0.1.dev279/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,177 @@
+# 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/examples/connect_bridge.py

@@ -0,0 +1,101 @@
+#!/usr/bin/env python3
+"""
+Example showing how to connect to a Philips Hue bridge.
+This is a good first script to run when setting up phue.
+"""
+
+import json
+import logging
+import os
+import sys
+
+from phue2 import Bridge, Light, PhueRegistrationException, console
+
+logging.basicConfig(level=logging.WARNING, format="%(levelname)s: %(message)s")
+
+
+def light_formatter(light: Light) -> str:
+    """Format a light for display in a table."""
+    status = "ON" if light.on else "OFF"
+    return f"{light.name:<25} - Status: {status}"
+
+
+def main():
+    """Connect to the Hue bridge and save credentials."""
+    console.header("Philips Hue Bridge Setup")
+
+    config_path = os.path.expanduser("~/.python_hue")
+
+    if os.path.exists(config_path):
+        try:
+            with open(config_path) as f:
+                config = json.loads(f.read())
+                if config:
+                    console.info("Found existing Hue bridge configuration.")
+
+                    for ip_address in config:
+                        if "username" in config[ip_address]:
+                            console.info(f"Trying saved bridge at {ip_address}...")
+                            try:
+                                bridge = Bridge(ip=ip_address)
+                                lights = bridge.lights
+                                console.success(f"Connected to bridge at {ip_address}")
+                                console.table(lights, light_formatter)
+                                return
+                            except Exception as e:
+                                console.error(f"Couldn't connect to {ip_address}")
+                                console.info(f"Error details: {e}")
+
+                    console.warning("Couldn't connect with any saved bridges.")
+        except (json.JSONDecodeError, FileNotFoundError):
+            console.error("Config file exists but is invalid.")
+
+    console.section("Bridge Connection Setup")
+    console.info("You'll need to provide your bridge IP address.")
+    console.info(
+        "You can find it in the Hue app (Settings > My Bridge) or your router."
+    )
+
+    ip_address = input("\nEnter your bridge IP address: ")
+    if not ip_address:
+        console.error("No IP address provided. Exiting.")
+        sys.exit(1)
+
+    while True:
+        console.section("Link Button Authentication")
+        console.warning("You need to press the link button on your Hue bridge.")
+        console.box(
+            "IMPORTANT",
+            [
+                "You only have 30 seconds to press the button!",
+                "Get ready to walk over to your bridge...",
+            ],
+        )
+
+        input("\nPress Enter when you're ready to go press the button...")
+
+        try:
+            console.info("Attempting to register with the bridge...")
+            bridge = Bridge(ip=ip_address)
+            console.success("Connected and saved credentials!")
+
+            console.section("Your Hue Lights")
+            console.table(bridge.lights, light_formatter)
+
+            console.success("Setup complete! You can now control your Hue lights.")
+            break
+
+        except PhueRegistrationException:
+            console.error("Link button was not pressed in time.")
+            console.warning("Let's try again. Remember, you only have 30 seconds!")
+
+        except Exception as e:
+            console.error(f"Connection failed: {e}")
+            retry = input("\nTry again? (y/n): ")
+            if retry.lower() != "y":
+                console.error("Exiting. Please try again later.")
+                sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

phue2-0.0.1.dev279/examples/flicker.py

@@ -0,0 +1,54 @@
+"""
+This script will have all lights flicker randomly.
+
+WARNING: If you have not previously connected to the bridge, run connect_bridge.py first.
+"""
+
+import random
+from time import sleep
+
+from phue2 import Bridge
+
+b = Bridge()
+b.connect()
+lights = b.lights
+
+
+def select_multiple_lights() -> list[int]:
+    """
+    Selects a random number of lights from the list of lights every time, resulting in a 'flickering' look.
+    """
+    return random.choices(range(1, len(lights) + 1), k=random.randint(1, len(lights)))
+
+
+def multi_modal():
+    """
+    Generates a random transition time between 0.2 and 0.7 seconds folowing a multi-modal distribution.
+    This results in really fast transitions, but also slow transitions.
+    """
+    return [
+        2 + int(random.betavariate(1, 9) * 5),
+        2 + int(random.betavariate(9, 1) * 5),
+    ][bool(random.getrandbits(1))]
+
+
+def candle_flicker():
+    """
+    Sends a command to change a certain number of lights a different color temperature every time. ct_inc was finicky, so I've used ct instead.
+    All inputs use a beta distribution, as it looked more natural. A similar look can be achieved using a triangular distribution as well.
+    """
+    b.set_light(
+        select_multiple_lights(),
+        {
+            "transitiontime": multi_modal(),
+            "on": True,
+            "bri": 1 + int(random.betavariate(2, 5) * 253),
+            "ct": 153 + int(random.betavariate(9, 4) * 347),
+        },
+    )
+
+
+if __name__ == "__main__":
+    while True:
+        candle_flicker()
+        sleep(random.random())