lghorizon 0.9.0.dev3__tar.gz → 0.9.1__tar.gz

{lghorizon-0.9.0.dev3 → lghorizon-0.9.1}/.github/workflows/build-on-pr.yml

@@ -11,7 +11,7 @@ jobs:
     steps:
     - uses: actions/checkout@master
     - name: Set up Python 3.10
-      uses: actions/setup-python@v5
+      uses: actions/setup-python@v6
       with:
         python-version: '3.13'
     - name: Install pypa/build

{lghorizon-0.9.0.dev3 → lghorizon-0.9.1}/.github/workflows/publish-to-pypi.yml

@@ -12,7 +12,7 @@ jobs:
     steps:
     - uses: actions/checkout@master
     - name: Set up Python 3.10
-      uses: actions/setup-python@v5
+      uses: actions/setup-python@v6
       with:
         python-version: '3.13'
 

lghorizon-0.9.1/PKG-INFO

@@ -0,0 +1,189 @@
+Metadata-Version: 2.4
+Name: lghorizon
+Version: 0.9.1
+Summary: Python client for Liberty Global Horizon settop boxes
+Home-page: https://github.com/sholofly/LGHorizon-python
+Author: Rudolf Offereins
+Author-email: r.offereins@gmail.com
+License: MIT license
+Keywords: LG,Horizon,API,Settop box
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Natural Language :: English
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.6
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: paho-mqtt
+Requires-Dist: requests>=2.22.0
+Requires-Dist: backoff>=1.9.0
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# LG Horizon API Python Library
+
+A Python library to interact with and control LG Horizon set-top boxes. This library provides functionalities for authentication, real-time device status monitoring via MQTT, and various control commands for your Horizon devices.
+
+## Features
+
+- **Authentication**: Supports authentication using username/password or a refresh token. The library automatically handles access token refreshing.
+- **Device Management**: Discover and manage multiple LG Horizon set-top boxes associated with your account.
+- **Real-time Status**: Monitor device status (online/running/standby) and current playback information (channel, show, VOD, recording, app) through MQTT.
+- **Channel Information**: Retrieve a list of available channels and profile-specific favorite channels.
+- **Recording Management**:
+  - Get a list of all recordings.
+  - Retrieve recordings for specific shows.
+  - Check recording quota and usage.
+- **Device Control**: Send various commands to your set-top box:
+  - Power on/off.
+  - Play, pause, stop, rewind, fast forward.
+  - Change channels (up/down, direct channel selection).
+  - Record current program.
+  - Set player position for VOD/recordings.
+  - Display custom messages on the TV screen.
+  - Send emulated remote control key presses.
+- **Robustness**: Includes automatic MQTT reconnection with exponential backoff and token refresh logic to maintain a stable connection.
+
+## Installation
+
+```bash
+pip install lghorizon-python # (Replace with actual package name if different)
+```
+
+## Usage
+
+Here's a basic example of how to use the library to connect to your LG Horizon devices and monitor their state:
+
+First, create a `secrets.json` file in the root of your project with your LG Horizon credentials:
+
+```json
+{
+  "username": "your_username",
+  "password": "your_password",
+  "country": "nl" // e.g., "nl" for Netherlands, "be" for Belgium
+}
+```
+
+Then, you can use the library as follows:
+
+```python
+import asyncio
+import json
+import logging
+import aiohttp
+
+from lghorizon.lghorizon_api import LGHorizonApi
+from lghorizon.lghorizon_models import LGHorizonAuth
+
+_LOGGER = logging.getLogger(__name__)
+
+async def main():
+    logging.basicConfig(level=logging.INFO) # Set to DEBUG for more verbose output
+
+    with open("secrets.json", encoding="utf-8") as f:
+        secrets = json.load(f)
+        username = secrets.get("username")
+        password = secrets.get("password")
+        country = secrets.get("country", "nl")
+
+    async with aiohttp.ClientSession() as session:
+        auth = LGHorizonAuth(session, country, username=username, password=password)
+        api = LGHorizonApi(auth)
+
+        async def device_state_changed_callback(device_id: str):
+            device = devices[device_id]
+            _LOGGER.info(
+                f"Device {device.device_friendly_name} ({device.device_id}) state changed:\n"
+                f"  State: {device.device_state.state.value}\n"
+                f"  UI State: {device.device_state.ui_state_type.value}\n"
+                f"  Source Type: {device.device_state.source_type.value}\n"
+                f"  Channel: {device.device_state.channel_name or 'N/A'} ({device.device_state.channel_id or 'N/A'})\n"
+                f"  Show: {device.device_state.show_title or 'N/A'}\n"
+                f"  Episode: {device.device_state.episode_title or 'N/A'}\n"
+                f"  Position: {device.device_state.position or 'N/A'} / {device.device_state.duration or 'N/A'}\n"
+            )
+
+        try:
+            _LOGGER.info("Initializing LG Horizon API...")
+            await api.initialize()
+            devices = await api.get_devices()
+
+            for device in devices.values():
+                _LOGGER.info(f"Registering callback for device: {device.device_friendly_name}")
+                await device.set_callback(device_state_changed_callback)
+
+            _LOGGER.info("API initialized. Monitoring device states. Press Ctrl+C to exit.")
+            # Keep the script running to receive MQTT updates
+            while True:
+                await asyncio.sleep(3600) # Sleep for a long time, MQTT callbacks will still fire
+
+        except Exception as e:
+            _LOGGER.error(f"An error occurred: {e}", exc_info=True)
+        finally:
+            _LOGGER.info("Disconnecting from LG Horizon API.")
+            await api.disconnect()
+            _LOGGER.info("Disconnected.")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## Authentication
+
+The `LGHorizonAuth` class handles authentication. You can initialize it with a username and password, or directly with a refresh token if you have one. The library automatically refreshes access tokens as needed.
+
+```python
+# Using username and password
+auth = LGHorizonAuth(session, "nl", username="your_username", password="your_password")
+
+# Using a refresh token (e.g., if you've saved it from a previous session)
+# auth = LGHorizonAuth(session, "nl", refresh_token="your_refresh_token")
+```
+
+You can also set a callback to receive the updated refresh token when it's refreshed, allowing you to persist it for future sessions:
+
+```python
+def token_updated_callback(new_refresh_token: str):
+    print(f"New refresh token received: {new_refresh_token}")
+    # Here you would typically save this new_refresh_token
+    # to your secrets.json or other persistent storage.
+
+# After initializing LGHorizonApi:
+# api.set_token_refresh_callback(token_updated_callback)
+```
+
+## Error Handling
+
+The library defines custom exceptions for common error scenarios:
+
+- `LGHorizonApiError`: Base exception for all API-related errors.
+- `LGHorizonApiConnectionError`: Raised for network or connection issues.
+- `LGHorizonApiUnauthorizedError`: Raised when authentication fails (e.g., invalid credentials).
+- `LGHorizonApiLockedError`: A specific type of `LGHorizonApiUnauthorizedError` indicating a locked account.
+
+These exceptions allow for more granular error handling in your application.
+
+## Development
+
+To run the example script (`main.py`) from the repository:
+
+1.  Clone this repository.
+2.  Install dependencies: `pip install -r requirements.txt` (ensure `requirements.txt` is up-to-date).
+3.  Create a `secrets.json` file as described in the Usage section.
+4.  Run `python main.py`.

lghorizon-0.9.1/README.md

@@ -0,0 +1,151 @@
+# LG Horizon API Python Library
+
+A Python library to interact with and control LG Horizon set-top boxes. This library provides functionalities for authentication, real-time device status monitoring via MQTT, and various control commands for your Horizon devices.
+
+## Features
+
+- **Authentication**: Supports authentication using username/password or a refresh token. The library automatically handles access token refreshing.
+- **Device Management**: Discover and manage multiple LG Horizon set-top boxes associated with your account.
+- **Real-time Status**: Monitor device status (online/running/standby) and current playback information (channel, show, VOD, recording, app) through MQTT.
+- **Channel Information**: Retrieve a list of available channels and profile-specific favorite channels.
+- **Recording Management**:
+  - Get a list of all recordings.
+  - Retrieve recordings for specific shows.
+  - Check recording quota and usage.
+- **Device Control**: Send various commands to your set-top box:
+  - Power on/off.
+  - Play, pause, stop, rewind, fast forward.
+  - Change channels (up/down, direct channel selection).
+  - Record current program.
+  - Set player position for VOD/recordings.
+  - Display custom messages on the TV screen.
+  - Send emulated remote control key presses.
+- **Robustness**: Includes automatic MQTT reconnection with exponential backoff and token refresh logic to maintain a stable connection.
+
+## Installation
+
+```bash
+pip install lghorizon-python # (Replace with actual package name if different)
+```
+
+## Usage
+
+Here's a basic example of how to use the library to connect to your LG Horizon devices and monitor their state:
+
+First, create a `secrets.json` file in the root of your project with your LG Horizon credentials:
+
+```json
+{
+  "username": "your_username",
+  "password": "your_password",
+  "country": "nl" // e.g., "nl" for Netherlands, "be" for Belgium
+}
+```
+
+Then, you can use the library as follows:
+
+```python
+import asyncio
+import json
+import logging
+import aiohttp
+
+from lghorizon.lghorizon_api import LGHorizonApi
+from lghorizon.lghorizon_models import LGHorizonAuth
+
+_LOGGER = logging.getLogger(__name__)
+
+async def main():
+    logging.basicConfig(level=logging.INFO) # Set to DEBUG for more verbose output
+
+    with open("secrets.json", encoding="utf-8") as f:
+        secrets = json.load(f)
+        username = secrets.get("username")
+        password = secrets.get("password")
+        country = secrets.get("country", "nl")
+
+    async with aiohttp.ClientSession() as session:
+        auth = LGHorizonAuth(session, country, username=username, password=password)
+        api = LGHorizonApi(auth)
+
+        async def device_state_changed_callback(device_id: str):
+            device = devices[device_id]
+            _LOGGER.info(
+                f"Device {device.device_friendly_name} ({device.device_id}) state changed:\n"
+                f"  State: {device.device_state.state.value}\n"
+                f"  UI State: {device.device_state.ui_state_type.value}\n"
+                f"  Source Type: {device.device_state.source_type.value}\n"
+                f"  Channel: {device.device_state.channel_name or 'N/A'} ({device.device_state.channel_id or 'N/A'})\n"
+                f"  Show: {device.device_state.show_title or 'N/A'}\n"
+                f"  Episode: {device.device_state.episode_title or 'N/A'}\n"
+                f"  Position: {device.device_state.position or 'N/A'} / {device.device_state.duration or 'N/A'}\n"
+            )
+
+        try:
+            _LOGGER.info("Initializing LG Horizon API...")
+            await api.initialize()
+            devices = await api.get_devices()
+
+            for device in devices.values():
+                _LOGGER.info(f"Registering callback for device: {device.device_friendly_name}")
+                await device.set_callback(device_state_changed_callback)
+
+            _LOGGER.info("API initialized. Monitoring device states. Press Ctrl+C to exit.")
+            # Keep the script running to receive MQTT updates
+            while True:
+                await asyncio.sleep(3600) # Sleep for a long time, MQTT callbacks will still fire
+
+        except Exception as e:
+            _LOGGER.error(f"An error occurred: {e}", exc_info=True)
+        finally:
+            _LOGGER.info("Disconnecting from LG Horizon API.")
+            await api.disconnect()
+            _LOGGER.info("Disconnected.")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## Authentication
+
+The `LGHorizonAuth` class handles authentication. You can initialize it with a username and password, or directly with a refresh token if you have one. The library automatically refreshes access tokens as needed.
+
+```python
+# Using username and password
+auth = LGHorizonAuth(session, "nl", username="your_username", password="your_password")
+
+# Using a refresh token (e.g., if you've saved it from a previous session)
+# auth = LGHorizonAuth(session, "nl", refresh_token="your_refresh_token")
+```
+
+You can also set a callback to receive the updated refresh token when it's refreshed, allowing you to persist it for future sessions:
+
+```python
+def token_updated_callback(new_refresh_token: str):
+    print(f"New refresh token received: {new_refresh_token}")
+    # Here you would typically save this new_refresh_token
+    # to your secrets.json or other persistent storage.
+
+# After initializing LGHorizonApi:
+# api.set_token_refresh_callback(token_updated_callback)
+```
+
+## Error Handling
+
+The library defines custom exceptions for common error scenarios:
+
+- `LGHorizonApiError`: Base exception for all API-related errors.
+- `LGHorizonApiConnectionError`: Raised for network or connection issues.
+- `LGHorizonApiUnauthorizedError`: Raised when authentication fails (e.g., invalid credentials).
+- `LGHorizonApiLockedError`: A specific type of `LGHorizonApiUnauthorizedError` indicating a locked account.
+
+These exceptions allow for more granular error handling in your application.
+
+## Development
+
+To run the example script (`main.py`) from the repository:
+
+1.  Clone this repository.
+2.  Install dependencies: `pip install -r requirements.txt` (ensure `requirements.txt` is up-to-date).
+3.  Create a `secrets.json` file as described in the Usage section.
+4.  Run `python main.py`.

lghorizon-0.9.1/lghorizon/__init__.py

@@ -0,0 +1,74 @@
+"""Python client for LG Horizon."""
+
+from .lghorizon_api import LGHorizonApi
+from .lghorizon_device import LGHorizonDevice
+from .lghorizon_models import (
+    LGHorizonAuth,
+    LGHorizonChannel,
+    LGHorizonCustomer,
+    LGHorizonDeviceState,
+    LGHorizonProfile,
+    LGHorizonRecording,
+    LGHorizonRecordingList,
+    LGHorizonShowRecordingList,
+    LGHorizonRecordingSeason,
+    LGHorizonRecordingSingle,
+    LGHorizonRecordingShow,
+    LGHorizonRecordingQuota,
+    LGHorizonRecordingType,
+    LGHorizonUIStateType,
+    LGHorizonMessageType,
+    LGHorizonRunningState,
+    LGHorizonRecordingSource,
+    LGHorizonRecordingState,
+    LGHorizonSourceType,
+    LGHorizonPlayerState,
+    LGHorizonAppsState,
+    LGHorizonUIState,
+    LGHorizonProfileOptions,
+    LGHorizonServicesConfig,
+)
+from .exceptions import (
+    LGHorizonApiError,
+    LGHorizonApiConnectionError,
+    LGHorizonApiUnauthorizedError,
+    LGHorizonApiLockedError,
+)
+
+from .const import COUNTRY_SETTINGS
+
+__all__ = [
+    "LGHorizonApi",
+    "LGHorizonDevice",
+    "LGHorizonAuth",
+    "LGHorizonChannel",
+    "LGHorizonCustomer",
+    "LGHorizonDeviceState",
+    "LGHorizonProfile",
+    "LGHorizonApiError",
+    "LGHorizonApiConnectionError",
+    "LGHorizonApiUnauthorizedError",
+    "LGHorizonApiLockedError",
+    "LGHorizonRecordingList",
+    "LGHorizonRecordingSeason",
+    "LGHorizonRecordingSingle",
+    "LGHorizonRecordingShow",
+    "LGHorizonRecordingQuota",
+    "LGHorizonRecordingType",
+    "LGHorizonUIStateType",
+    "LGHorizonMessageType",
+    "LGHorizonRunningState",
+    "LGHorizonRecordingSource",
+    "LGHorizonRecordingState",
+    "LGHorizonSourceType",
+    "LGHorizonPlayerState",
+    "LGHorizonAppsState",
+    "LGHorizonUIState",
+    "LGHorizonProfileOptions",
+    "LGHorizonProfile",
+    "LGHorizonAuth",
+    "LGHorizonServicesConfig",
+    "LGHorizonRecording",
+    "LGHorizonShowRecordingList",
+    "COUNTRY_SETTINGS",
+]

lghorizon-0.9.1/lghorizon/const.py

@@ -0,0 +1,90 @@
+"""Python client for LGHorizon."""
+
+# flake8: noqa
+# Box states
+ONLINE_RUNNING = "ONLINE_RUNNING"
+ONLINE_STANDBY = "ONLINE_STANDBY"
+UNKNOWN = "UNKNOWN"
+
+BOX_PLAY_STATE_CHANNEL = "linear"
+BOX_PLAY_STATE_REPLAY = "replay"
+BOX_PLAY_STATE_DVR = "nDVR"
+BOX_PLAY_STATE_BUFFER = "reviewbuffer"
+BOX_PLAY_STATE_APP = "app"
+BOX_PLAY_STATE_VOD = "VOD"
+
+# List with available media keys.
+MEDIA_KEY_POWER = "Power"
+MEDIA_KEY_ENTER = "Enter"
+MEDIA_KEY_ESCAPE = "Escape"  # Not yet implemented
+
+MEDIA_KEY_HELP = "Help"  # Not yet implemented
+MEDIA_KEY_INFO = "Info"  # Not yet implemented
+MEDIA_KEY_GUIDE = "Guide"  # Not yet implemented
+
+MEDIA_KEY_CONTEXT_MENU = "ContextMenu"  # Not yet implemented
+MEDIA_KEY_CHANNEL_UP = "ChannelUp"
+MEDIA_KEY_CHANNEL_DOWN = "ChannelDown"
+
+MEDIA_KEY_RECORD = "MediaRecord"
+MEDIA_KEY_PLAY_PAUSE = "MediaPlayPause"
+MEDIA_KEY_STOP = "MediaStop"
+MEDIA_KEY_REWIND = "MediaRewind"
+MEDIA_KEY_FAST_FORWARD = "MediaFastForward"
+
+RECORDING_TYPE_SINGLE = "single"
+RECORDING_TYPE_SHOW = "show"
+RECORDING_TYPE_SEASON = "season"
+
+BE_AUTH_URL = "https://login.prd.telenet.be/openid/login.do"
+
+PLATFORM_TYPES = {
+    "EOS": {"manufacturer": "Arris", "model": "DCX960"},
+    "EOS2": {"manufacturer": "HUMAX", "model": "2008C-STB-TN"},
+    "HORIZON": {"manufacturer": "Arris", "model": "DCX960"},
+    "APOLLO": {"manufacturer": "Arris", "model": "VIP5002W"},
+}
+
+COUNTRY_SETTINGS = {
+    "nl": {
+        "api_url": "https://spark-prod-nl.gnp.cloud.ziggogo.tv",
+        "mqtt_url": "obomsg.prod.nl.horizon.tv",
+        "use_refreshtoken": False,
+        "name": "Ziggo",
+    },
+    "ch": {
+        "api_url": "https://spark-prod-ch.gnp.cloud.sunrisetv.ch",
+        "use_refreshtoken": True,
+        "name": "UPC Switzerland",
+    },
+    "be-basetv": {
+        "api_url": "https://spark-prod-be.gnp.cloud.base.tv",
+        "use_refreshtoken": True,
+        "name": "BASE TV (BE)",
+    },
+    "be-nl": {
+        "api_url": "https://spark-prod-be.gnp.cloud.telenet.tv",
+        "use_refreshtoken": True,
+        "name": "Telenet (BE)",
+    },
+    "be-nl-preprod": {
+        "api_url": "https://spark-preprod-be.gnp.cloud.telenet.tv",
+        "use_refreshtoken": True,
+        "name": "Telenet (BE, PREPROD)",
+    },
+    "gb": {
+        "api_url": "https://spark-prod-gb.gnp.cloud.virgintvgo.virginmedia.com",
+        "use_refreshtoken": True,
+        "name": "Virgin Media (GB)",
+    },
+    "ie": {
+        "api_url": "https://spark-prod-ie.gnp.cloud.virginmediatv.ie",
+        "use_refreshtoken": False,
+        "name": "Virgin Media (IE)",
+    },
+    "pl": {
+        "api_url": "https://spark-prod-pl.gnp.cloud.upctv.pl",
+        "use_refreshtoken": False,
+        "name": "UPC (PL)",
+    },
+}

{lghorizon-0.9.0.dev3 → lghorizon-0.9.1}/lghorizon/exceptions.py

@@ -6,12 +6,12 @@ class LGHorizonApiError(Exception):
 
 
 class LGHorizonApiConnectionError(LGHorizonApiError):
-    """Generic LGHorizon exception."""
+    """Exception for connection-related errors with the LG Horizon API."""
 
 
 class LGHorizonApiUnauthorizedError(Exception):
-    """Generic LGHorizon exception."""
+    """Exception for unauthorized access to the LG Horizon API."""
 
 
 class LGHorizonApiLockedError(LGHorizonApiUnauthorizedError):
-    """Generic LGHorizon exception."""
+    """Exception for locked account errors with the LG Horizon API."""